Repositories

What are repositories?

If you’re confused by the name Repositories, that’s completely normal.

I actually received emails from people thinking there was a bug in Charcole because a repositories folder was created automatically. Some assumed it referred to GitHub repositories or version control. It doesn’t. There is nothing related to GitHub here at all.

In Charcole, repositories mean something very specific and very intentional.

Repositories are the place where all database-related logic lives.

Nothing more. Nothing less.

Why repositories exist in Charcole

While building backend projects over the years, one recurring problem kept showing up again and again.

Backend work almost always depends on the database, but database setup rarely happens at the same pace as API development. Sometimes the schema isn’t finalized. Sometimes the database server isn’t ready. Sometimes another developer is responsible for it and timelines don’t align.

This leads to a frustrating situation where API development is blocked, not because logic is complex, but because data isn’t available yet.

Charcole introduces repositories to break this dependency.

Instead of tying your API logic directly to a real database from day one, repositories act as a stable contract between your application and your data source. Whether the data comes from a real database, a mocked object, or a temporary in-memory store does not matter to the rest of the system.

This allows development to move forward independently.

What repositories actually do

A repository’s responsibility is simple:
it knows how data is stored and retrieved.

That’s it.

Repositories answer questions like:

• How do we fetch a user?
• How do we store a record?
• How do we update or delete data?

They do not decide why something happens, and they do not care who requested it. They only care about data.

This clear responsibility is what makes repositories powerful.

Repositories without a real database

One of the most important design goals of Charcole repositories is that they work even when no database exists.

In early stages of a project, charcole repositories can return mocked data, hardcoded objects, or simple in-memory arrays. Your API routes, controllers, and services can be fully developed, tested, and validated without waiting days or weeks for database readiness.

Later, when the real database is ready, you replace the internals of the repository — not the entire application.

Nothing else breaks.

This approach dramatically improves development speed and removes unnecessary blockers.

Separation that actually matters

Charcole Repositories create a very strong separation between business logic and data access.

Your controllers and services never need to know:

• Which database you are using
• Which ORM you chose
• Whether queries are complex or simple

They only know that a repository provides data in a certain shape.

This separation is not just an architectural preference — it is what allows projects to grow without collapsing under their own complexity.

Why repositories make codebases healthier

As projects grow, codebases usually degrade in predictable ways. Database queries start appearing everywhere. Business rules get mixed with SQL or ORM calls. Testing becomes difficult because everything depends on everything else.

Charcole Repositories stop this decay early.

They centralize data access, enforce discipline, and make it obvious where database logic belongs. When a bug appears related to data, you know exactly where to look. When performance needs tuning, repositories are the first and only stop.

Over time, this leads to a calmer, more readable, and more maintainable backend.

Repositories and long-term flexibility

One of the most underrated benefits of repositories is future flexibility.

Changing databases is never fun, but without repositories it becomes terrifying. With repositories in place, the blast radius of such a change is limited. You update how data is fetched and stored in one layer, while the rest of the application remains untouched.

Even if you never change databases, this flexibility gives you confidence. Your architecture is not fragile. It can evolve.

Final thoughts

Repositories in Charcole are not there to add complexity.
They are there to remove chaos.

They allow you to:

• Build APIs before databases are ready
• Keep business logic clean
• Avoid tight coupling with data sources
• Scale the codebase without fear

If Charcole had to enforce only one architectural idea, repositories would be it.

They quietly do their job, stay out of your way, and protect your project as it grows — which is exactly what good architecture should do.