# iduprojects/idu_api architecture

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

- Interactive diagram: https://gitdiagram.com/iduprojects/idu_api
- Repository: https://github.com/iduprojects/idu_api

## Overview

##### Project Type and Purpose
- This project is a backend API service built to work with an urban database. It is divided into at least two API applications:
- urban_api: The “Actual API in development to manipulate data in urban_db” (as described in the README).
- city_api: An updated API that replaces an older feature-service, reworking the database schema and microservices.
- In addition, there are utility scripts (in the duty directory) to perform tasks like geometry corrections and regenerating project previews, indicating some scheduled/background processing.
- The system is designed using microservice principles, with distinct modules for handling different aspects (API endpoints, DB migrations, service logic, etc.) and Docker configurations provided for containerized deployment.

##### Key Components
- Front-facing Services:
- Urban API Service: Handles urban-related API requests and encapsulates endpoints, business logic (controllers, DTOs, service classes, etc.), exception handling, and middlewares.
- City API Service: Focused on manipulating and exposing data from a legacy perspective while transitioning to a microservices-based architecture.
- Core Backend Infrastructure:
- Database: Although not shown as a separate repository, the migrations and DB connection files (e.g., under idu_api/common/db, alembic scripts, and entity definitions) indicate a relational database or similar persistent storage. Show the database as a central component that both APIs interact with.
- DB Migration/ORM Layer: Modules for migrations, entity definitions, and connection managers are essential part of the persistence layer.
- Utility Scripts and Background Tasks:
- Duty Scripts: These include tasks like “fix_geometries” and “regenerate_projects_previews”, which interact with the database or file system. Represent these as a background processing component.
- Deployment and Containerization:
- Dockerfiles and docker-compose files for both urban_api and city_api (as well as the migration runners or testing environments) indicate containerized deployment. Represent these as part of the deployment infrastructure.

##### Architectural Relationships and Flow
- Urban API and City API:
- These services likely share common lower-level modules (via idu_api) such as configuration and DB connection management, so include a common shared component representing “idu_api Common Modules”.
- Database Layer:
- Sub-components representing the DB migration tools (alembic scripts and entity definitions).
- Utility / Task Schedulers (Duty Scripts):
- How these scripts are triggered possibly on a schedule or via external trigger, interacting directly with the database and file systems to update or correct data.
- External Dependencies:
- If appropriate, note additional external services or libraries such as Prometheus for metrics gathering, given the existence of the "prometheus" files, and note integration with Minio (evidence from minio.env and associated client utilities) for object storage.

##### Design Patterns and Technologies
- The architecture leverages a modular design separated by concern. You see clear layers:
- API Layer (handlers, controllers, routes),
- Business Logic/Services Layer (service modules, mappers, DTOs),
- Data Access Layer (database connection managers and ORM-like patterns),
- Background Task Layer (duty scripts).
- Use dependency injection (visible in “dependency_injection.py” and middleware) and robust exception handling patterns (present in “exception_handler.py” and corresponding exception directories).
- Adoption of containerization (Docker, docker-compose) stresses the importance of deployment consistency across environments.
- Technologies likely include FastAPI (based on file naming and folder structure), Alembic for DB migrations, and additional libraries for logging, authentication, and metrics.

##### Final Recommendations
- Remember that clarity is key: simplicity in presentation (even if the internal component responsibilities are complex) will help stakeholders and fellow engineers understand the system quickly.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients Layer
    Client["Client (Mobile/Web)"]:::external

    %% API Services Layer
    subgraph "API Services"
        subgraph "Urban API Service"
            UrbanAPI_Primary["Urban API Primary Code<br/>(handles urban_db data manipulation)"]:::api
            UrbanAPI_Root["Urban API Root API"]:::api
            UrbanAPI_Primary --> UrbanAPI_Root
        end
        subgraph "City API Service"
            CityAPI_Primary["City API Primary Code<br/>(legacy data manipulation & microservice transition)"]:::api
            CityAPI_Root["City API Root API"]:::api
            CityAPI_Primary --> CityAPI_Root
        end
    end

    %% Connections from Client to API Services
    Client -->|"request"| UrbanAPI_Primary
    Client -->|"request"| CityAPI_Primary

    %% Shared Core Modules Layer
    subgraph "Common Modules"
        CommonModules["Common Modules & Configurations"]:::common
        DB_Entities["Database Connection & Entities"]:::db
        DB_Migrations["DB Migration Scripts"]:::db
        CommonModules --> DB_Entities
        DB_Entities --> DB_Migrations
    end

    %% Database Layer
    Database["Database"]:::database

    %% API Services connect to Common Modules and Database
    UrbanAPI_Primary -->|"uses"| CommonModules
    CityAPI_Primary -->|"uses"| CommonModules
    UrbanAPI_Primary -->|"CRUD"| Database
    CityAPI_Primary -->|"CRUD"| Database

    %% Common Modules connects to Database
    DB_Entities -->|"connects"| Database

    %% Utility / Background Tasks Layer
    subgraph "Utility / Background Tasks"
        Duty_Fix["Duty: fix_geometries"]:::utility
        Duty_Regenerate["Duty: regenerate_projects_previews"]:::utility
    end

    %% Utility scripts interact with Database
    Duty_Fix -->|"updates"| Database
    Duty_Regenerate -->|"updates"| Database

    %% Deployment and Containerization Layer
    subgraph "Deployment & Containerization"
        Urban_Dockerfile["Urban API Dockerfile"]:::deployment
        Urban_DCompose["Urban API docker-compose"]:::deployment
        City_Dockerfile["City API Dockerfile"]:::deployment
        City_DCompose["City API docker-compose"]:::deployment
        Migrations_Dockerfile["Migrations Dockerfile"]:::deployment
    end

    %% External Services
    subgraph "External Integrations"
        Prometheus["Prometheus<br/>(Monitoring)"]:::external
        Minio["Minio<br/>(Object Storage)"]:::external
    end

    %% Deployment supports API services and migrations
    UrbanAPI_Primary -->|"deployed via"| Urban_Dockerfile
    UrbanAPI_Primary -->|"deployed via"| Urban_DCompose
    CityAPI_Primary -->|"deployed via"| City_Dockerfile
    CityAPI_Primary -->|"deployed via"| City_DCompose
    DB_Migrations -->|"ran via"| Migrations_Dockerfile

    %% External integrations interact with API services and Database
    UrbanAPI_Primary -->|"sends metrics to"| Prometheus
    CityAPI_Primary -->|"sends metrics to"| Prometheus
    Database -->|"stores objects"| Minio

    %% Click Events for Component Mapping
    click UrbanAPI_Primary "https://github.com/iduprojects/idu_api/tree/main/idu_api/urban_api"
    click UrbanAPI_Root "https://github.com/iduprojects/idu_api/tree/main/urban_api"
    click CityAPI_Primary "https://github.com/iduprojects/idu_api/tree/main/idu_api/city_api"
    click CityAPI_Root "https://github.com/iduprojects/idu_api/tree/main/city_api"
    click CommonModules "https://github.com/iduprojects/idu_api/tree/main/idu_api/common"
    click DB_Entities "https://github.com/iduprojects/idu_api/tree/main/idu_api/common/db"
    click DB_Migrations "https://github.com/iduprojects/idu_api/tree/main/idu_api/common/db/migrator"
    click Duty_Fix "https://github.com/iduprojects/idu_api/tree/main/duty/scripts/fix_geometries"
    click Duty_Regenerate "https://github.com/iduprojects/idu_api/tree/main/duty/scripts/regenerate_projects_previews"
    click Urban_Dockerfile "https://github.com/iduprojects/idu_api/tree/main/urban_api/Dockerfile"
    click Urban_DCompose "https://github.com/iduprojects/idu_api/blob/main/urban_api/docker-compose.yaml"
    click City_Dockerfile "https://github.com/iduprojects/idu_api/tree/main/city_api/Dockerfile"
    click City_DCompose "https://github.com/iduprojects/idu_api/blob/main/city_api/docker-compose.yaml"
    click Migrations_Dockerfile "https://github.com/iduprojects/idu_api/blob/main/migrations.Dockerfile"

    %% Styles
    classDef api fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef common fill:#e2e3e5,stroke:#383d41,stroke-width:2px;
    classDef db fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef utility fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef deployment fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef external fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
```
