# danxvv/banpayghibli architecture

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

- Interactive diagram: https://gitdiagram.com/danxvv/banpayghibli
- Repository: https://github.com/danxvv/banpayghibli

## Overview

##### Project Type and Purpose
- The project is a backend API built using FastAPI that provides complete CRUD operations on a users table, along with role-based access control and integration with an external Ghibli API. It also includes authentication (using JWT), database migrations with Alembic, and it is fully containerized using Docker Compose.

##### File Structure
- The top-level project includes configuration files (Dockerfile, docker-compose.yml, .env.example), setup scripts (entrypoint.sh), and documentation (README.md, Postman collection).
- The “src” directory is the main application code. It is organized into:
- An “auth” module for authentication routes and schemas.
- A “ghibli” module dedicated to calling the Ghibli API.
- A “users” module that handles user models, routes, services, and repositories.
- A “database” module that manages SQLAlchemy sessions and configurations.
- Utility code in the “utils” module.
- Migration scripts reside in the “alembic” folder, indicating database schema management.
- Tests are separated in the “tests” directory.

##### README for Architectural Insights
- The README outlines key API endpoints for authentication, users, roles, and Ghibli data.
- It mentions the use of technologies (Python, FastAPI, SQLAlchemy, Alembic, PostgreSQL, Docker) that should be part of the system design.
- Guidance is provided for local development (via Docker) and includes detailed API endpoint interactions, which help in understanding data flows and security roles.

a. Main Components to Include:
- API Server:
- FastAPI application (src/main.py) hosting the endpoints.
- Route modules: auth routes (src/auth), users routes (src/users), and ghibli routes (src/ghibli).
- Database:
- PostgreSQL (as configured via Docker Compose and SQLAlchemy in src/database).
- Alembic module used for migration/versioning.
- Authentication Component:
- JWT authentication handled in auth module with helper functions (e.g., in src/utils/security.py).
- External Service:
- Ghibli API integration defined in src/ghibli/services.py.
- Docker Infrastructure:
- Dockerfile and docker-compose.yml that containerize the API and the database.
- Testing Environment:
- Unit/integration tests in the tests folder.

b. Relationships and Interactions:
- The API Server interacts with:
- The Database module for CRUD operations (through SQLAlchemy sessions and models defined under src/users/models.py).
- The External Ghibli API via the designated service (src/ghibli/services.py) triggered based on specific user roles.
- The Authentication component secures endpoints and manages token generation as defined in the auth routes.
- Each module (auth, users, ghibli) is connected through a central router (src/router.py), ensuring that every route is accessible via versioned endpoint paths as described in the README.
- Docker Compose orchestrates the containers, ensuring the API service and PostgreSQL run and communicate properly.

c. Architectural Patterns and Technologies:
- MVC-like structure: Models (src/users/models.py), Views/Routes (various routes in respective modules), and Controllers/Services.
- Dependency injection: Likely used in FastAPI (see src/dependencies.py) to inject database sessions, authentication services into endpoints.
- Containerization: Deployment is handled via Docker and Docker Compose.
- Security: JWT-based token authentication managed via utility modules.
- External integration: The project incorporates an external API call (to the Ghibli API) that is conditionally triggered by user roles.

d. Relevant Technologies:
- FastAPI for the API framework.
- SQLAlchemy for ORM/database interactions.
- Alembic for migrations.
- PostgreSQL as the database.
- Docker and Docker Compose for containerization.
- JWT for secure authentication.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Docker Environment
    subgraph "Docker Environment"
        %% API Container
        subgraph "API Container"
            APIServer["FastAPI Server"]:::internal
            AuthModule["Auth Module"]:::internal
            UsersModule["Users Module"]:::internal
            GhibliModule["Ghibli API Module"]:::internal
            ConfigMgmt["Config Management"]:::internal
            DBManagement["Database Management"]:::internal
            DockerInfra["Docker Infrastructure"]:::internal
        end

        %% Database Container
        subgraph "Database Container"
            PostgresDB["PostgreSQL DB"]:::database
            DBMigrations["DB Migrations (Alembic)"]:::database
        end
    end

    %% External and Testing Components
    ExternalGhibli["External Ghibli API"]:::external
    TestingEnv["Testing Environment"]:::internal
    Client["Client"]:::external

    %% Relationships
    Client -->|"sendsRequests"| APIServer
    APIServer -->|"routesTo"| AuthModule
    APIServer -->|"routesTo"| UsersModule
    APIServer -->|"routesTo"| GhibliModule
    APIServer -->|"loadsConfigFrom"| ConfigMgmt
    APIServer -->|"usesDB"| DBManagement
    DBManagement -->|"interactsWith"| PostgresDB
    DBManagement -->|"usesMigrations"| DBMigrations
    APIServer -->|"callsAPI"| ExternalGhibli
    TestingEnv -->|"tests"| APIServer
    DockerInfra -->|"orchestrates"| APIServer
    DockerInfra -->|"orchestrates"| PostgresDB

    %% Click Events
    click APIServer "https://github.com/danxvv/banpayghibli/blob/main/src/main.py"
    click APIServer "https://github.com/danxvv/banpayghibli/blob/main/src/router.py"
    click AuthModule "https://github.com/danxvv/banpayghibli/blob/main/src/auth/routes.py"
    click AuthModule "https://github.com/danxvv/banpayghibli/blob/main/src/auth/schemas.py"
    click AuthModule "https://github.com/danxvv/banpayghibli/blob/main/src/utils/security.py"
    click UsersModule "https://github.com/danxvv/banpayghibli/blob/main/src/users/models.py"
    click UsersModule "https://github.com/danxvv/banpayghibli/blob/main/src/users/routes.py"
    click UsersModule "https://github.com/danxvv/banpayghibli/blob/main/src/users/schemas.py"
    click UsersModule "https://github.com/danxvv/banpayghibli/blob/main/src/users/services.py"
    click UsersModule "https://github.com/danxvv/banpayghibli/tree/main/src/users/repos"
    click GhibliModule "https://github.com/danxvv/banpayghibli/blob/main/src/ghibli/services.py"
    click GhibliModule "https://github.com/danxvv/banpayghibli/blob/main/src/ghibli/routes.py"
    click DBManagement "https://github.com/danxvv/banpayghibli/tree/main/src/database"
    click DBMigrations "https://github.com/danxvv/banpayghibli/tree/main/alembic"
    click DockerInfra "https://github.com/danxvv/banpayghibli/tree/main/Dockerfile"
    click DockerInfra "https://github.com/danxvv/banpayghibli/blob/main/docker-compose.yml"
    click DockerInfra "https://github.com/danxvv/banpayghibli/blob/main/entrypoint.sh"
    click ConfigMgmt "https://github.com/danxvv/banpayghibli/blob/main/.env.example"
    click ConfigMgmt "https://github.com/danxvv/banpayghibli/blob/main/src/config.py"
    click TestingEnv "https://github.com/danxvv/banpayghibli/tree/main/tests"

    %% Styles
    classDef internal fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef external fill:#A9DFBF,stroke:#145A32,stroke-width:2px;
    classDef database fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
```
