# lizarti/mars-rover-server architecture

> Architecture diagram of the GitHub repository lizarti/mars-rover-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lizarti/mars-rover-server
- Repository: https://github.com/lizarti/mars-rover-server

## Overview

##### Main components
- API Layer (HTTP Interface)
- Located under src/api – includes controllers (e.g., home, mission, rover, world), DTOs (for request/response structures), and middlewares (e.g., logger middleware).
- Provides the entry point (via Express) for incoming requests.
- Application Layer (Use Cases)
- Under src/application – this layer contains use-cases like “add-rover”, “create-mission”, “create-world”, etc.
- It coordinates between the API and Domain layers by executing business rules and orchestrating domain operations.
- Domain Layer (Business Logic and Models)
- Found under src/domain – this includes enums, exceptions, interfaces, models (mission, rover, world), and domain services.
- This layer encapsulates business rules and is independent of frameworks or external systems.
- Infrastructure Layer (Persistence, External Services, and Server Setup)
- Under src/infra – handles all external interactions such as database access (via Knex repositories and migrations), logging (in infra/logging), and web server details (via Express in infra/web).
- The “database” folder includes datasource configuration, entity definitions, and migration files.
- Additional Utilities and Configurations:
- Utilities (src/utils) for functions like UUID generation and planet-specific utilities.
- Environment configuration files (.env.example) and Docker-related configurations (Dockerfile, .dockerignore).

##### Relationships and interactions
- The API Controllers (in the API Layer) accept incoming HTTP requests. They use DTOs to validate and format data.
- Requests are passed to the respective use-case classes in the Application Layer, which orchestrate business logic by leveraging domain models and domain services.
- The Domain Layer handles business rules—including checking for valid rover positions, mission instructions, etc.—and communicates with repository interfaces.
- The Infrastructure Layer is responsible for data persistence. Its Knex-based repositories map domain models to database entities. It also logs events and serves the web endpoints via Express.
- The interactions are directed and layered: the flow generally is from External Request → API (Express Server & Middleware) → Application (Use Cases) → Domain (Models/Services) → Infrastructure (Repositories, Database, Logging).

##### Architectural patterns and design principles
- Layered (or Hexagonal) Architecture: Clear separation of concerns between presentation, application logic, domain rules, and infrastructure.
- Dependency Inversion: The domain and application layers define repository interfaces; the actual implementations in the infrastructure layer (e.g., Knex) depend on these abstractions.
- Use of DTOs ensures that data contracts between the API and backend logic remain consistent.
- The existence of specialized directories (controllers, middlewares, use-cases, services) points to a modular design that enhances testing (note the unit test folders with “.spec.ts” files).

##### Relevant technologies and frameworks
- Node.js, Express (for HTTP server and routing)
- Knex.js (database migration and query building)
- Sqlite3 (database by default; possibility to switch to MySQL/PostgreSQL via environment variables)
- TypeScript (based on .ts file extension)
- Logging Library (Consola or similar in infra/logging)
- Testing with Jest (jest.config.js hints at unit testing)

##### Instructing the principal software engineer
- Client request flows to API controllers.
- API controllers trigger use-case execution in the Application Layer.
- Application layer interacts with Domain logic.
- Domain layer calls Infrastructure components for persistence or external communication.

## Diagram (Mermaid)

```mermaid
graph TD
    Client["Client_Request"]:::external
    subgraph "API Layer"
        APIC["Express_Server (Controllers,DTOs,Middlewares)"]:::api
    end
    subgraph "Application Layer"
        APP["Use_cases (add-rover,create-mission,etc.)"]:::app
    end
    subgraph "Domain Layer"
        DOM["Domain_Logic (Models,Services,Rules)"]:::domain
    end
    subgraph "Infrastructure Layer"
        INFRA["Persistence_&_External_Services (Knex_Repos,Database,Logging)"]:::infra
    end
    UTILS["Utilities_&_Configurations"]:::utils

    Client -->|"HTTP_Request"| APIC
    APIC -->|"Execute_UseCase"| APP
    APP -->|"Business_Logic"| DOM
    DOM -->|"DB_Query"| INFRA

    APIC -.->|"Utility_Call"| UTILS
    APP -.->|"Utility_Call"| UTILS
    INFRA -.->|"Utility_Call"| UTILS

    click APIC "https://github.com/lizarti/mars-rover-server/tree/main/src/api"
    click APP "https://github.com/lizarti/mars-rover-server/tree/main/src/application"
    click DOM "https://github.com/lizarti/mars-rover-server/tree/main/src/domain"
    click INFRA "https://github.com/lizarti/mars-rover-server/tree/main/src/infra"
    click UTILS "https://github.com/lizarti/mars-rover-server/tree/main/src/utils"

    classDef external fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef api fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef app fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef domain fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef infra fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef utils fill:#d6d8d9,stroke:#383d41,stroke-width:2px;
```
