# esturide/esturide-api architecture

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

- Interactive diagram: https://gitdiagram.com/esturide/esturide-api
- Repository: https://github.com/esturide/esturide-api

## Overview

The Esturide API is a backend service built with FastAPI and Docker, designed to provide robust, scalable API services for the Esturide platform. The project adheres to a layered architecture that separates concerns into distinct components such as presentation, application, domain, infrastructure, and core utilities/dependencies.

##### Project Type and Purpose
- This is a backend API for a platform, intended to facilitate operations like authentication, travel matching, ride scheduling, and real-time status updates using sockets/SSE.
- The use of FastAPI indicates an emphasis on high performance and ease of integration with modern client applications.
- Containerization through Docker and orchestration via Docker Compose further emphasize a microservice or service-oriented approach.

##### File Structure and Main Components
a. Presentation Layer:
- Located under "app/presentation" and its subdirectories, this layer handles API endpoints.
- It contains separate components for RESTful endpoints (e.g., "api", "health", "user_management") and API schemes for data validation.

b. Application Layer:
- Found in "app/application/uses_cases", this layer includes use case implementations (e.g., auth, automobile, rate, ride, schedule, status with both socket and HTTP interfaces).
- This layer orchestrates business logic by calling domain services or managing workflows.

c. Domain Layer:
- Resides under "app/domain" and includes models, types, services, and factories (e.g., services for auth, travel, user, etc.).
- It encapsulates business rules and domain logic, maintaining the system’s core functionality.

d. Infrastructure Layer:
- Present in "app/infrastructure/repository", it contains implementations interfacing with external systems such as databases.
- It includes repository implementations for authentication, driver, automobile, tracking, etc.

e. Core Utilities and Dependencies:
- Found under "app/core", this part contains configurations, database dependencies (e.g., for Neo4j and Redis), exception handling, encryption, OAuth2, and session management (including websockets and SSE management).
- This layer bridges connections with external systems and provides necessary cross-cutting concerns.

##### Important Architectural Patterns and Design Principles
- The project follows a layered or clean architecture approach, separating presentation, application, domain, and infrastructure concerns.
- Use of dependency injection (notably under "app/core/dependencies") facilitates testing and modularity.
- Communication patterns include both synchronous HTTP (via REST APIs) and asynchronous real-time updates using WebSocket and SSE protocols.

##### Additional Details for the Principal Software Engineer
- Layer/component is clearly labeled and annotated, explaining its role.
- Security aspects such as OAuth2 integration within the Core layer.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["External Client"]:::external

    %% Docker Container boundary for the Esturide API
    subgraph "Docker Container: Esturide API"
        direction TB

        Pres["Presentation Layer: FastAPI Endpoints"]:::presentation
        App["Application Layer: Use Cases"]:::application
        Dom["Domain Layer: Domain Logic"]:::domain
        Infra["Infrastructure Layer: Repositories"]:::infrastructure
        Core["Core Utilities & Dependencies"]:::core
    end

    %% External Databases (Neo4j, Redis)
    CoreDB["Neo4j/Redis Database"]:::database

    %% Data Flow
    Client -->|"HTTP/WS Request"| Pres
    Pres -->|"API Call"| App
    App -->|"Executes Business Logic"| Dom
    App -->|"Data Operations"| Infra
    App -->|"Uses Config/Dependencies"| Core
    Dom -->|"Calls Domain Services"| Infra
    Pres -->|"RealTime (WS/SSE) Updates"| Core
    Core -->|"Manages DB Connections"| CoreDB

    %% Click Events
    click Pres "https://github.com/esturide/esturide-api/tree/master/app/presentation"
    click App "https://github.com/esturide/esturide-api/tree/master/app/application/uses_cases"
    click Dom "https://github.com/esturide/esturide-api/tree/master/app/domain"
    click Infra "https://github.com/esturide/esturide-api/tree/master/app/infrastructure/repository"
    click Core "https://github.com/esturide/esturide-api/tree/master/app/core"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:2px
    classDef presentation fill:#ffcccc,stroke:#cc0000,stroke-width:2px
    classDef application fill:#ccffcc,stroke:#009900,stroke-width:2px
    classDef domain fill:#ccccff,stroke:#3333cc,stroke-width:2px
    classDef infrastructure fill:#ffffcc,stroke:#cccc00,stroke-width:2px
    classDef core fill:#d9d9d9,stroke:#808080,stroke-width:2px
    classDef database fill:#e6ffe6,stroke:#006600,stroke-width:2px
```
