Initial commit

ARCHITECTURE.md

@@ -0,0 +1,82 @@
+# Project Architecture
+
+This document outlines the architectural decisions, project structure, and key patterns used in the `express-starter` project.
+
+## Overview
+
+The project follows a **Modular Monolith** architecture combined with **Clean Architecture** (also known as Hexagonal Architecture or Ports and Adapters) principles. This ensures separation of concerns, maintainability, and testability by isolating business logic from infrastructure details.
+
+## Directory Structure
+
+The source code is located in the `src` directory and is organized into two main categories:
+
+- **`src/modules`**: Contains feature-specific modules (e.g., `users`, `auth`). Each module is a self-contained vertical slice of the application.
+- **`src/shared`**: Contains code shared across multiple modules, such as base classes, utilities, and common infrastructure.
+
+### Module Anatomy (`src/modules/<module-name>`)
+
+Each module follows a strict layering strategy:
+
+1.  **`domain/`**: The core business logic.
+    -   **Entities**: Pure TypeScript interfaces/classes defining the domain models (e.g., `UserEntity`).
+    -   **Repository Interfaces**: Contracts defining how data is accessed (e.g., `IUsersRepository`).
+    -   **Domain Services**: Business logic that doesn't fit into a single entity.
+    -   *Dependencies*: This layer has **zero** dependencies on outer layers or external libraries (except strictly utility libraries).
+
+2.  **`use-cases/`**: Application-specific business rules.
+    -   Contains classes that orchestrate the flow of data to and from the domain entities.
+    -   Implements specific user actions (e.g., `RegisterUserUseCase`, `UserSignup`).
+    -   *Dependencies*: Depends on the `domain` layer.
+
+3.  **`infrastructure/`**: Implementation details and adapters.
+    -   **`persistence/`**: Database implementations of repositories (e.g., `UsersPostgresRepository`), database models, and mappers.
+    -   **`http/`**: HTTP controllers, routes, and request validation schemas (Zod).
+    -   **`di/`**: Dependency Injection configuration (InversifyJS modules).
+    -   *Dependencies*: Depends on `domain` and `use-cases`.
+
+### Shared Kernel (`src/shared`)
+
+-   **`core/`**: Core interfaces and types (e.g., `IBaseRepository`, `FilterQuery`).
+-   **`infrastructure/`**: Shared infrastructure implementations.
+    -   **`persistence/postgres/`**: Base repository implementations and database connection logic.
+    -   **`http/`**: Base router, HTTP utilities, and middlewares (e.g., `requestLogger`, `attachRequestContext`).
+    -   **`crypto/`**: Cryptographic utilities (e.g., hashing, token generation).
+    -   **`logger/`**: Logging service configuration.
+    -   **`di/`**: Global DI container setup.
+
+## Key Technologies & Patterns
+
+### Dependency Injection (DI)
+The project uses **InversifyJS** for dependency injection.
+-   **Container**: A global `appContainer` is defined in `src/shared/infrastructure/di/Container.ts`.
+-   **Modules**: Each feature module exports a `ContainerModule` (e.g., `UsersDIModule`) which binds interfaces to implementations.
+-   **Usage**: Dependencies are injected into classes (Repositories, Use Cases) using the `@inject` decorator.
+
+### Repository Pattern
+Data access is abstracted using the Repository Pattern.
+-   **Interface**: Defined in the Domain layer (e.g., `IUsersRepository`).
+-   **Implementation**: Defined in the Infrastructure layer (e.g., `UsersPostgresRepository`).
+-   **Base Repository**: A generic `PostgresBaseRepository` in `shared` provides common CRUD operations.
+
+### Validation
+**Zod** is used for runtime validation, particularly for HTTP request bodies in the controller/route layer.
+
+### Database
+**Postgres** is the underlying database. The project uses **Prisma ORM** for schema definition, migrations, and type-safe database access. The repository layer wraps Prisma Client calls.
+
+### Authentication & Authorization
+The `auth` module handles user authentication.
+-   **Strategy**: Likely uses JWT (JSON Web Tokens) for stateless authentication.
+-   **Crypto**: Shared crypto services handle password hashing (e.g., Argon2 or Bcrypt) and token signing.
+
+## Data Flow
+
+A typical request flows as follows:
+
+1.  **HTTP Request** hits a Route defined in `infrastructure/http`.
+2.  **Middlewares** (Global/Route-specific) run (e.g., logging, context attachment).
+3.  **Validation** validates the request payload using Zod.
+4.  **Use Case** is resolved from the DI container and executed.
+5.  **Repository** is called by the Use Case to fetch/save data.
+6.  **Domain Entity** is returned/manipulated.
+7.  **Response** is sent back to the client.