Introduce to Quantum Modular Architecture

# Go Project Structure Guide

This document defines a standard, production-ready package structure and a set of engineering principles for building robust, flexible, and scalable Go applications. Its purpose is to provide a clear and consistent blueprint that can be easily understood and automated by Large Language Models (LLMs) for code generation.

### Strict Rules to Follow

These are the non-negotiable rules of this architecture. They must be strictly followed to maintain the integrity of the structure.

1.  **Absolute Separation of Interface and Implementation**: All interfaces **must** be defined within the `lib` package. All concrete implementations of those interfaces **must** be created within the `pkg` package.
2.  **`internal/service` Dependency Rule**: The `internal/service` layer **must only** depend on the `lib` package. It must **never** depend on `internal/controller`.
3.  **`internal/controller` Dependency Rule**: The `internal/controller` layer can depend on `internal/service` and the `lib` package. It must **never** depend on `pkg` or `cmd`.
4.  **`cmd` Layer's Role**: The `cmd` layer is the **only** layer that can depend on all other internal layers (`internal/controller`, `internal/service`) and `pkg`. Its sole purpose is to "wire" everything together.

### Directory Structure and Roles

*   `**/cmd/**`: The application's entry point (`main` package). Its sole responsibility is to assemble dependencies (wiring `pkg` implementations into `internal` components) and start the application. Each subdirectory is a runnable application and must contain its own `Dockerfile`.
*   `**/internal/**`: Contains the application's business logic (`controller`, `service`).
    *   `**internal/controller/**`: Handles incoming requests (e.g., HTTP, gRPC), calls the appropriate `service`, and transforms the result into a response.
    *   `**internal/service/**`: Executes core business logic and orchestrates use cases. This is the **only** layer where multiple interfaces from `lib` are combined (composed) to create complex business flows. For example, a service might use a `repository` interface and a `notification` adapter interface together.
    *   `**internal/tests/**`: Contains integration tests that verify the interaction between multiple components (e.g., service and database).
*   `**/lib/**`: The project's most fundamental abstraction layer. Defines technology-agnostic **interfaces** and data structures. It contains **no concrete implementation code**.
    *   `**lib/domain/**`: Defines core business entities and their intrinsic business rules.
    *   `**lib/repository/**`: Defines interfaces for data persistence.
    *   `**lib/adapter/**`: Defines interfaces for external services like loggers or payment gateways.
        *   `**lib/adapter/gen/**`: Contains code generated by `buf`.
*   `**/pkg/**`: Contains the **concrete implementations** of the interfaces defined in `lib`. All infrastructure-related code resides here. 
    *   A `pkg` implementation must be a self-contained, minimal implementation of a single `lib` interface (e.g., implementing the `Repository` interface from the `lib/repository/{entity}` package using `sqlc` and `pgx`).
    *   It **must not** compose other `lib` interfaces by holding them as fields. The responsibility of combining different functionalities belongs exclusively to the `internal/service` layer.
    *   **Client Wrapping Pattern for Multiple Interfaces**: When a single technology package (e.g., `pkg/client/{technology}`) needs to implement multiple `lib` interfaces (e.g., `{entity1}.Cache`, `{entity2}.Cache`), a wrapping pattern **must** be used.
        1.  A central `client.go` file should define the core client struct (e.g., `type Client struct { ... }`) that manages the underlying connection (e.g., to Redis).
        2.  Each `lib` interface implementation should be in its own file (e.g., `{entity1}_cache.go`, `{entity2}_cache.go`).
        3.  Each implementation struct will wrap the core client (e.g., `type {Entity1}Cache struct { client *Client }`) and use it to implement the specific interface methods. This promotes code reuse and clear separation of concerns within the package.
    *   When implementing an interface from `lib`, it is **mandatory** to include a compile-time check to ensure the struct correctly implements the interface. Use the following pattern directly below the import statements: `var _ lib_package.InterfaceName = (*StructName)(nil)`. 
    *   Unit tests for each implementation must be located within the same package.
*   `**/proto/**`: Stores the original Interface Definition Language (IDL) files, such as Protocol Buffers (`.proto`).

### Tooling and Code Generation

#### Protobuf & gRPC (`buf`)

*   **Source Location**: All `.proto` source files **must** be located in the `proto/` directory.
*   **Generated Code Destination**: Code generated by `buf` **must** be placed in the `lib/adapter/gen/` directory.
*   **Configuration Template (`buf.yaml`)**:
    ```yaml
    version: v1
    name: buf.build/your-org/your-project
    deps:
      - buf.build/googleapis/googleapis
    breaking:
      use:
        - FILE
    lint:
      use:
        - DEFAULT
    ```
*   **Generation Template (`buf.gen.yaml`)**:
    ```yaml
    version: v1
    plugins:
      - plugin: buf.build/protocolbuffers/go:v1.31.0
        out: lib/adapter/gen
        opt: paths=source_relative
      - plugin: buf.build/grpc/go:v1.3.0
        out: lib/adapter/gen
        opt: paths=source_relative
    ```

*   **Tool Dependency Management (Go 1.24+ Recommended)**: It is recommended to manage the `buf` CLI as a versioned tool dependency. This ensures that all developers and CI environments use the exact same version of the tool.

    1.  **Add the tool to `go.mod`**: Run `go get -tool buf.build/buf/cmd/buf` to add it as a tool dependency.
    2.  **Usage**: Run `go tool buf generate` to execute the version defined in your `go.mod`.

### Code Style & Conventions

#### Error Handling Practices

*   **Error Wrapping**: When propagating an error from a lower layer to a higher one, it **must** be wrapped with context using `fmt.Errorf("description of what failed: %w", err)`. This creates a traceable error stack.

#### Documentation Style (godoc)

*   **`godoc` Comments**: All exported functions, types, variables, and constants **must** have a `godoc`-style comment that starts with the name of the element it is documenting. The comment should clearly explain its purpose and usage.

### Testing Strategy

*   **Unit Tests**: Located within the `pkg` package they are testing. They must test components in isolation by mocking external dependencies.
*   **Integration Tests**: Located in the `internal/tests/` directory. They test the interaction between multiple components, often with real external services like a database running in Docker.
*   **End-to-End (E2E) Tests**: Located within the relevant `cmd` package. They test the entire application by making requests to its public interface (e.g., HTTP API).

### Build and Deployment

*   **`Dockerfile`**: Each runnable application in a `cmd/*` directory **must** have its own `Dockerfile`. Multi-stage builds should be used to create lean production images.
*   **`docker-compose.yaml`**: Located at the project root with environment-specific names (e.g., `dev.docker-compose.yaml`). These files define the local development and testing environments.

### Conventional Main File Names

To maintain consistency, it is recommended to use standardized file names for the main logic within each package type. The file name should reflect the package's primary role.

*   `cmd/{app_name}/` → `app.go` (or `main.go`)
*   `internal/controller/{feature_api}/` → `controller.go` (or `handler.go`)
*   `internal/service/{business_logic}/` → `service.go`
*   `pkg/client/{technology}/` → `client.go`
*   `pkg/client/{technology}/` → `repository_{repository_name}.go`
*   `lib/repository/{entity}/` → `{entity}.go`
*   `lib/domain/{entity}/` → `{entity}.go`