# inf-inf/hackathon_more_tech_5_back architecture

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

- Interactive diagram: https://gitdiagram.com/inf-inf/hackathon_more_tech_5_back
- Repository: https://github.com/inf-inf/hackathon_more_tech_5_back

## Overview

##### Project Type and Purpose
- It’s a backend service with a REST API (using uvicorn to run the ASGI app) that supports functionalities such as showing branch/ATM location data, calculating walking/automobile routes, and analyzing branch load.
- The README mentions algorithmic decision-making for optimal branch selection, route building (possibly integrating third-party mapping services), logging history, and implementing security/auth flows via tokens and phone authentication.

##### File Structure – Main Components
- Application Layer:
- In the src/app folder, the main API application (api_app.py) is defined.
- Lifespan management (src/app/lifespan) handles startup routines, possibly initializing dependencies or database connections.
- Middleware (src/app/middleware) includes security-related routines that intercept or validate requests.

- Caching:
- The src/cache folder holds modules for caching logic like SMS and security, which may be used to optimize repeated operations (e.g., one-time token generation or throttling API calls).

- Database Layer:
- The src/database directory contains the base connection logic, models (defining ORM/schema objects), and CRUD operations separated into modules (e.g., history.py for logging or locations.py for dealing with branch details).

- Business Logic and Dependencies:
- Business logic is organized in the src/logic folder and also appears in dedicated dependencies folders:
- src/dependencies/database for connection handling.
- src/dependencies/logic with modules to process history, locations, and users.
- src/dependencies/security for security (and in src/models/security for additional structure).

- Routing and Schemas:
- API endpoints are implemented via routers (src/routers) which map URL paths to specific functionalities such as history, locations, service, and user.
- Validation and data structures are defined in the src/schemas folder.

- Supplemental Data and Documentation:
- The data folder includes JSON files (for atms and offices) which may be used as seed data or as a part of the service’s input.
- The docs folder contains a preview PDF, likely used for design or explanation of the service.

##### Relationships and Interactions Between Components
- The entry point (src/main.py) starts up the API application, instantiating the ASGI app.
- The API layer (src/app/api_app.py) routes incoming HTTP requests to the appropriate routers in src/routers.
- Routers interface with business logic found in src/logic and src/dependencies/logic to process requests.
- These logic layers handle interactions with the database layer (src/database) through CRUD operations to read/write the necessary data.
- Middleware and security dependencies manage authentication by leveraging components from src/dependencies/security and src/cache/security.
- Caching may be used in endpoints to avoid repeated expensive operations (e.g., sending SMS for token auth).

##### Architectural Patterns & Design Principles
- Layered or modular architecture: Clear separation between API (routing), business logic, data access (CRUD & models), and dependencies.
- Scalability considerations: Though it’s currently monolithic, the README indicates that the design allows the backend to be split into modules later (e.g., separate modules for reviews, queue management, etc.).
- Clear separation of concerns: Each folder represents a distinct responsibility (e.g., lifecycle management, caching, routing).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% API Layer
    subgraph "API Layer"
        APIApp["API Application"]:::api
        Lifespan["Lifecycle / Startup"]:::lifecycle
        Middleware["Middleware & Security"]:::middleware
        SecurityDep["Security Dependency"]:::middleware
    end

    %% Routing Layer
    subgraph "Routing Layer"
        Routers["Routers"]:::routers
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        CoreLogic["Core Business Logic"]:::logic
        DepLogic["Dependency Business Logic"]:::logic
    end

    %% Data Layer
    subgraph "Data Layer"
        DBModels["Database Models"]:::database
        DBCRUD["Database CRUD Operations"]:::database
        Cache["Cache"]:::cache
    end

    %% External Data & Documentation
    subgraph "External & Docs"
        ATMs["ATMs Data"]:::external
        Offices["Offices Data"]:::external
        Docs["Documentation"]:::doc
    end

    %% Connections
    Lifespan -->|"init"| APIApp
    Middleware -->|"token_validation"| SecurityDep
    Middleware -->|"validate_token"| APIApp
    APIApp -->|"HTTP_Request"| Routers
    Routers -->|"process"| CoreLogic
    Routers -->|"process"| DepLogic
    CoreLogic -->|"read/write"| DBModels
    CoreLogic -->|"query"| DBCRUD
    DepLogic -->|"read/write"| DBModels
    DepLogic -->|"query"| DBCRUD
    CoreLogic -->|"cache_lookup"| Cache
    DepLogic -->|"cache_lookup"| Cache
    CoreLogic -->|"seed_data"| ATMs
    CoreLogic -->|"seed_data"| Offices

    %% Click Events
    click APIApp "https://github.com/inf-inf/hackathon_more_tech_5_back/blob/main/src/app/api_app.py"
    click Lifespan "https://github.com/inf-inf/hackathon_more_tech_5_back/blob/main/src/app/lifespan/startup.py"
    click Middleware "https://github.com/inf-inf/hackathon_more_tech_5_back/blob/main/src/app/middleware/security.py"
    click SecurityDep "https://github.com/inf-inf/hackathon_more_tech_5_back/tree/main/src/dependencies/security/"
    click Routers "https://github.com/inf-inf/hackathon_more_tech_5_back/tree/main/src/routers/"
    click CoreLogic "https://github.com/inf-inf/hackathon_more_tech_5_back/tree/main/src/logic/"
    click DepLogic "https://github.com/inf-inf/hackathon_more_tech_5_back/tree/main/src/dependencies/logic/"
    click DBModels "https://github.com/inf-inf/hackathon_more_tech_5_back/blob/main/src/database/models.py"
    click DBCRUD "https://github.com/inf-inf/hackathon_more_tech_5_back/tree/main/src/database/crud/"
    click Cache "https://github.com/inf-inf/hackathon_more_tech_5_back/tree/main/src/cache/"
    click ATMs "https://github.com/inf-inf/hackathon_more_tech_5_back/blob/main/data/atms.json"
    click Offices "https://github.com/inf-inf/hackathon_more_tech_5_back/blob/main/data/offices.json"
    click Docs "https://github.com/inf-inf/hackathon_more_tech_5_back/blob/main/docs/preview.pdf"

    %% Styles
    classDef api fill:#FFCC00,stroke:#333,stroke-width:2px;
    classDef lifecycle fill:#FFEEAA,stroke:#333,stroke-width:2px;
    classDef middleware fill:#FFAAAA,stroke:#333,stroke-width:2px;
    classDef routers fill:#AAF,stroke:#333,stroke-width:2px;
    classDef logic fill:#CFF,stroke:#333,stroke-width:2px;
    classDef database fill:#FFC,stroke:#333,stroke-width:2px;
    classDef cache fill:#CCF,stroke:#333,stroke-width:2px;
    classDef external fill:#CFC,stroke:#333,stroke-width:2px;
    classDef doc fill:#FCC,stroke:#333,stroke-width:2px;
```
