# nanotaboada/python-samples-fastapi-restful architecture

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

- Interactive diagram: https://gitdiagram.com/nanotaboada/python-samples-fastapi-restful
- Repository: https://github.com/nanotaboada/python-samples-fastapi-restful

## Overview

##### Project type and purpose
- This is a monolithic RESTful API implemented in Python 3 using FastAPI.
- Purpose: expose CRUD endpoints for “player” resources backed by a SQLite database.

##### File structure
- Top‐level files:
- main.py – entry point where FastAPI app and routers are mounted
- Dockerfile, .github/workflows/python-app.yml – deployment and CI/CD
- Directories:
- routes/ – HTTP route handlers (controllers)
- services/ – business logic layer
- models/ – ORM or in‐memory models representing domain entities
- schemas/ – Pydantic schemas for request/response validation
- data/ – persistence layer (player_database.py + SQLite file)
- tests/ – unit and integration tests
- Config files: requirements*.txt, .flake8, .pylintrc, codecov.yml – code quality and lint/test definitions

##### Insights from README
- Confirms layered flow: request → route handler → service → data access → database
- Includes a simplified structure.svg illustrating the conceptual flow

##### Main components
a. External Clients
- Web browser / HTTP client (e.g., Postman, Swagger UI)
b. API Gateway / FastAPI Server
- Uvicorn ASGI server running main:app
c. Route Handlers (routes/player_route.py)
d. Service Layer (services/player_service.py)
e. Data Access Layer (data/player_database.py)
f. Persistence (players-sqlite3.db)
g. Optional: CI/CD pipelines and Docker container

##### Relationships and data flows
- Client → HTTP Request → Uvicorn / FastAPI
- FastAPI → dispatch to route handlers
- Route handler → calls service layer
- Service layer → invokes data access functions
- Data access → reads/writes SQLite database
- Response bubbles back up layers to client
- Docker image wraps Uvicorn + app, exposes port 9000
- CI/CD jobs run tests, lint, code coverage on push

##### Architectural patterns and principles
- Layered (hexagonal-like) architecture: controllers → services → repository
- Separation of concerns: request validation (schemas), business logic (services), persistence (data)
- Dependency injection via FastAPI’s built-in DI for request bodies and services
- Single codebase (monolith), but logically modularized

##### Technologies and frameworks
- FastAPI (router, DI, automatic Swagger UI)
- Uvicorn (ASGI server)
- Pydantic schemas for validation
- SQLite for local dev persistence
- Docker multi-stage build for dev/prod
- GitHub Actions for CI/CD, SonarCloud/Codacy/Codecov for quality gates

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    Client["HTTP Client\n(Postman/Swagger UI)"]:::external

    %% Docker Container Boundary
    subgraph "Docker Container\n(port 9000)"
        direction TB
        Uvicorn["Uvicorn ASGI Server\nmain.py"]:::api
        Route["Route: player_route.py"]:::api
        Schema["Schema: player_schema.py"]:::api
        Model["Model: player_model.py"]:::api
        Service["Service: player_service.py"]:::service
        DataAccess["Data Access: player_database.py"]:::data
        DB["SQLite DB: players-sqlite3.db"]:::data
    end

    %% External DevOps
    DockerfileNode["Dockerfile"]:::external
    CI["CI/CD Pipeline\n(.github/workflows/python-app.yml)"]:::external
    Tests["Tests Directory\n(tests/)"]:::external

    %% Data Flow
    Client -->|"GET /players"| Uvicorn
    Uvicorn -->|"dispatch request"| Route
    Route -->|"validate via Pydantic"| Schema
    Route -->|"calls service"| Service
    Service -->|"uses domain model"| Model
    Service -->|"query repository"| DataAccess
    DataAccess -->|"SQL SELECT/INSERT"| DB
    DB -->|"query result"| DataAccess
    DataAccess -->|"returns domain objects"| Service
    Service -->|"convert to DTO"| Schema
    Schema -->|"response JSON"| Route
    Route -->|"200 OK JSON"| Uvicorn
    Uvicorn -->|"HTTP response"| Client

    %% DevOps interactions
    DockerfileNode -.-> Uvicorn
    CI -.-> DockerfileNode
    CI -.-> Tests

    %% Click Events
    click Uvicorn "https://github.com/nanotaboada/python-samples-fastapi-restful/blob/master/main.py"
    click Route "https://github.com/nanotaboada/python-samples-fastapi-restful/blob/master/routes/player_route.py"
    click Schema "https://github.com/nanotaboada/python-samples-fastapi-restful/blob/master/schemas/player_schema.py"
    click Model "https://github.com/nanotaboada/python-samples-fastapi-restful/blob/master/models/player_model.py"
    click Service "https://github.com/nanotaboada/python-samples-fastapi-restful/blob/master/services/player_service.py"
    click DataAccess "https://github.com/nanotaboada/python-samples-fastapi-restful/blob/master/data/player_database.py"
    click DB "https://github.com/nanotaboada/python-samples-fastapi-restful/blob/master/data/players-sqlite3.db"
    click DockerfileNode "https://github.com/nanotaboada/python-samples-fastapi-restful/tree/master/Dockerfile"
    click CI "https://github.com/nanotaboada/python-samples-fastapi-restful/blob/master/.github/workflows/python-app.yml"
    click Tests "https://github.com/nanotaboada/python-samples-fastapi-restful/tree/master/tests/"

    %% Styles
    classDef api fill:#D0E6FF,stroke:#000,stroke-width:1px;
    classDef service fill:#D3F9D8,stroke:#000,stroke-width:1px;
    classDef data fill:#FFE5B4,stroke:#000,stroke-width:1px;
    classDef external fill:#E8E8E8,stroke-dasharray: 5 5,stroke:#000;
```
