The Cillop Architecture

Lean, Flexible and Compatible

In today’s rapidly evolving tech world, having a scalable, maintainable, and understandable project structure is a key element. The Cillop architecture, inspired by the principles of Clean Architecture, offers just that. Let's take a closer look.

The architecture overview

Before it all starts, what does ‘cillop’ mean?

“It was like a Cillop” is a Turkish idiom and expresses that something was done perfectly, very well, perfectly or better than expected. It is often used when describing the outcome of a job or activity. For example, when a recipe is tried and the result is amazing, it can be said that it was “like a cillop”. This expression carries a positive meaning and indicates that something happened above expectations.

The Philosophy Behind the Architecture 🧠

When building an application, there’s always a struggle between external libraries, database design, server frameworks, and your core business rules. The essence of Cillop is to put business logic at the center and maintain a clear separation between these components.

The Layers of Cillop Architecture 🍰

The architecture can be visualized as a set of concentric circles, each representing a different layer of the software:

Interfaces (Remote Client)

• Represents the outermost layer.
• It’s the point of entry for external clients, where requests are initiated.

Interface Adapter (Servers Directory)

• This layer handles the interaction between the remote client and the application’s core functionality.
• It’s where we find our HTTP servers, RPC interfaces, and even event-stream mechanisms.

Application Business Logic (Commands and Queries)

• This is the heart of our application. It’s where use-cases are defined and executed.
• Commands refer to actions that result in state changes, while queries refer to actions that retrieve data.
• This separation ensures a clear distinction between operations that modify data and those that read data.

Enterprise Business Logic (Domains)

• Represents the core business rules and entities.
• Independent of any external concerns, keeping the business logic pure and free from side-effects.

Walking Through the Directory Structure 📁

• app: Holds our application-specific business logic. Here you find the commands for modifying state and queries for reading data.
• cmd: Main entry point for our applications.
• config: Configuration settings and constants for our project.
• locales: Localization files to support multiple languages.
• pkg: Shared packages across the architecture. From cqrs mechanisms to database-specific code such as mongodb, and even domain-specific logic in domains.
• server: The Interface Adapters. It contains different interfaces such as http, rpc, and event-stream.

You can find the sample project here. For Quick view, the folder structure in this example is as follows:

📦cillop
 ┣ 📂app
 ┃ ┣ 📂command
 ┃ ┃ ┗ 📜product_create.go
 ┃ ┣ 📂query
 ┃ ┃ ┗ 📜product_get.go
 ┃ ┗ 📜app.go
 ┣ 📂cmd
 ┃ ┗ 📜main.go
 ┣ 📂config
 ┃ ┗ 📜config.go
 ┣ 📂locales
 ┃ ┗ 📜en.toml
 ┣ 📂pkg
 ┃ ┣ 📂cqrs
 ┃ ┃ ┗ 📜cqrs.go
 ┃ ┣ 📂domains
 ┃ ┃ ┗ 📂product
 ┃ ┃ ┃ ┣ 📜entity.go
 ┃ ┃ ┃ ┣ 📜msg.go
 ┃ ┃ ┃ ┗ 📜repo.go
 ┃ ┣ 📂mongodb
 ┃ ┃ ┣ 📜collection.go
 ┃ ┃ ┣ 📜mongo.go
 ┃ ┃ ┣ 📜mongo_test.go
 ┃ ┃ ┣ 📜uri.go
 ┃ ┃ ┗ 📜uri_test.go
 ┃ ┗ 📂server
 ┃ ┃ ┗ 📜server.go
 ┣ 📂server
 ┃ ┣ 📂event-stream
 ┃ ┃ ┣ 📜api.go
 ┃ ┃ ┗ 📜stream.go
 ┃ ┣ 📂http
 ┃ ┃ ┣ 📜api.go
 ┃ ┃ ┣ 📜http.go
 ┃ ┃ ┗ 📜msg.go
 ┃ ┗ 📂rpc
 ┃ ┃ ┣ 📂protos
 ┃ ┃ ┃ ┗ 📜product.proto
 ┃ ┃ ┣ 📂routes
 ┃ ┃ ┃ ┣ 📜product.pb.go
 ┃ ┃ ┃ ┗ 📜product_grpc.pb.go
 ┃ ┃ ┣ 📜api.go
 ┃ ┃ ┗ 📜rpc.go
 ┣ 📂service
 ┃ ┗ 📜application.go
 ┣ 📜Dockerfile
 ┣ 📜Dockerfile.dev
 ┣ 📜go.mod
 ┗ 📜go.sum

The example above is an example for golang. However, this architecture is quite far from golang and can adapt to any language.

Why Adopt the Cillop Architecture? 🤔

• Separation of Concerns: Each layer has a distinct responsibility, making it easier to modify one layer without affecting the others.
• Testability: With business logic decoupled from interface logic, unit testing becomes straightforward.
• Maintainability: New team members can quickly understand the codebase structure and where specific functionalities reside.
• Flexibility: Need to change the database or switch to a different server framework? With Cillop, you can do that without touching the core business logic.

Final Thoughts 🌟

Cillop is more than just a project structure. It's a philosophy that emphasizes the importance of business rules and ensures that other concerns like UI, databases, and frameworks play a supporting role, rather than dominating the architecture.

Whether you’re building a new project or refactoring an existing one, give the Cillop architecture a try and experience the difference.