cedar-api/ARCHITECTURE.md

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.