# 6g-sandbox/route-manager-api architecture

> Architecture diagram of the GitHub repository 6g-sandbox/route-manager-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/6g-sandbox/route-manager-api
- Repository: https://github.com/6g-sandbox/route-manager-api

## Overview

##### Project Type and Purpose
- This is a backend REST API built using FastAPI.
- Its main purpose is to manage network routes on a Linux machine via the “ip” command—with capabilities to query, add, update, pause, and delete routes—and it incorporates a scheduling mechanism that transitions routes through various states (pending, active, paused, expired, deleted). It also includes lifecycle management (a background loop), token-based authentication, and persistence with SQLite.

##### Main Components
a. API Layer:
- FastAPI server (from app/main.py) that handles HTTP requests.
- Endpoints defined in the routers (app/routers/routes.py) and note that authentication (via services/auth.py) is applied.

b. Service Layer:
- Module blocks for the services (app/services) responsible for:
- Authentication (auth.py)
- Route operations (routes.py)
- Lifecycle management (lifecycle.py that manages scheduled route activation/expiration)
- Utility functions (utils.py) that support operations.

c. Database Layer:
- Database connection and initialization (app/db/database.py).
- Two database models:
- Routes model (app/db/models/routes.py)
- Deleted routes model (app/db/models/deleted_routes.py)
- Additionally, indicate the interaction utilities (app/db/routes.py) that serve to interact with the database.

d. Schemas:
- How request and response data are validated/serialized using Pydantic schemas (app/schemas/routes.py).

e. Configuration and Logging:
- A block for core configuration (app/core/config.py) and global logging settings (app/core/logging.py).
- This highlights where application settings and logging behavior are defined.

f. External Interaction & System Integration:
- Optionally, represent the systemd service integration (as shown in the README’s instructions for running the service) which models production deployment.

##### Relationships and Interactions
- Client requests → FastAPI server.
- FastAPI server routes incoming HTTP requests to appropriate routers.
- Routers call service functions (e.g., for authentication, lifecycle, or route management) to process business logic.
- Services interact with the database layer for reading or updating route records.
- A continuous background “lifecycle loop” (from app/services/lifecycle.py) checks timestamps and updates route statuses.
- Logging is performed at multiple levels (both in the API layer and service layer) to record operations.

##### Architectural Patterns
- Separation of concerns: API (routing) layer, service/business logic layer, and the persistence layer.
- Use of FastAPI’s built-in dependency injection for request validation and the Pydantic models.
- Background loop design for lifecycle management, an important non-HTTP workflow in this system.

##### Relevant Technologies, Frameworks, and Libraries
- FastAPI (API framework)
- Python (core language, version 3.12+)
- SQLite (for persistence)
- Pydantic (for data validation and serialization)
- uv (project management tool managing Python versions and dependencies)
- Systemd (for service management)
- ‘ip’ command (for interaction with the Linux network stack)

## Diagram (Mermaid)

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

    %% API Layer
    subgraph "API Layer"
        FS["FastAPI Server"]:::api
        AE["API Endpoints"]:::api
    end

    %% Service Layer
    subgraph "Service Layer"
        Auth["Authentication Service"]:::service
        RM["Route Management Service"]:::service
        LM["Lifecycle Manager"]:::service
        Util["Utility Functions"]:::service
    end

    %% Database Layer
    subgraph "Database Layer"
        DB["Database Connection"]:::db
        AR["Active Routes Model"]:::db
        DR["Deleted Routes Model"]:::db
        DBI["DB Interaction Utility"]:::db
    end

    %% Schemas and Configuration
    subgraph "Schemas & Config"
        Schema["Pydantic Schemas"]:::config
        Config["Core Configuration"]:::config
        Logging["Global Logging"]:::config
    end

    %% External Systems
    subgraph "External Systems"
        Linux["Linux Network (ip command)"]:::external
        Systemd["Systemd Service"]:::external
    end

    %% Connections
    Client -->|"HTTP_Request"| FS
    FS -->|"routes"| AE
    FS -->|"reads_config"| Config
    FS -->|"logs"| Logging

    AE -->|"calls_auth"| Auth
    AE -->|"calls_routeMgmt"| RM
    AE -->|"validates_with"| Schema

    Auth -->|"uses_util"| Util
    RM -->|"uses_util"| Util

    Auth -->|"db_query"| DBI
    RM -->|"db_query"| DBI
    LM -->|"db_update"| DBI

    DBI -->|"uses_connection"| DB
    DBI -->|"manages_active"| AR
    DBI -->|"manages_deleted"| DR

    LM -->|"executes_ip"| Linux

    Systemd -->|"manages"| FS

    Auth -->|"logs"| Logging
    RM -->|"logs"| Logging
    LM -->|"logs"| Logging

    %% Click Events
    click FS "https://github.com/6g-sandbox/route-manager-api/blob/main/app/main.py"
    click AE "https://github.com/6g-sandbox/route-manager-api/blob/main/app/routers/routes.py"
    click Auth "https://github.com/6g-sandbox/route-manager-api/blob/main/app/services/auth.py"
    click RM "https://github.com/6g-sandbox/route-manager-api/blob/main/app/services/routes.py"
    click LM "https://github.com/6g-sandbox/route-manager-api/blob/main/app/services/lifecycle.py"
    click Util "https://github.com/6g-sandbox/route-manager-api/blob/main/app/services/utils.py"
    click DB "https://github.com/6g-sandbox/route-manager-api/blob/main/app/db/database.py"
    click AR "https://github.com/6g-sandbox/route-manager-api/blob/main/app/db/models/routes.py"
    click DR "https://github.com/6g-sandbox/route-manager-api/blob/main/app/db/models/deleted_routes.py"
    click DBI "https://github.com/6g-sandbox/route-manager-api/blob/main/app/db/routes.py"
    click Schema "https://github.com/6g-sandbox/route-manager-api/blob/main/app/schemas/routes.py"
    click Config "https://github.com/6g-sandbox/route-manager-api/blob/main/app/core/config.py"
    click Logging "https://github.com/6g-sandbox/route-manager-api/blob/main/app/core/logging.py"

    %% Styles
    classDef api fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef service fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef db fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef config fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
```
