# bdien/ludotheque architecture

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

- Interactive diagram: https://gitdiagram.com/bdien/ludotheque
- Repository: https://github.com/bdien/ludotheque

## Overview

##### Main Components

a. Frontend Layer (React Application)
- React application container
- Feature modules:
- User Management
- Inventory Management
- Loan Management
- Document Management
- Statistics/Reports

b. Backend Layer (FastAPI)
- API Server container
- Core service modules:
- Authentication/Users
- Bookings
- Items/Inventory
- Loans
- Ledger
- System Configuration

c. Data Layer
- Database (appears to use Peewee ORM)
- Storage system for game images
- Google Sheets integration (indicated by gsheets.py)

##### Component Relationships

- Frontend → Backend: REST API calls (shown by src/webui/src/api/calls.ts)
- Backend → Database: Peewee ORM interactions
- Backend → Storage: File system interactions for images
- Backend → External Services: Google Sheets API integration

##### Architectural Patterns to Highlight

- Clear separation of concerns (frontend/backend/data)
- RESTful API architecture
- Component-based frontend architecture (React)
- Service-based backend organization

##### Specific Implementation Details

Frontend (React):
- Component hierarchy
- State management (hooks/global_store.ts)
- UI component library (Material UI 5+)

Backend (FastAPI):
- Route handlers
- Service layers
- Authentication flow
- Email template system

##### Deployment Architecture

Deployment-specific components:
- Docker container (Dockerfile present)
- Nginx reverse proxy (setup/nginx.conf)
- Fly.io deployment (fly.toml)

##### External Services Layer

- Component types
- Important configuration files
- Testing coverage (src/tests_api)

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        Browser["Web Browser"]:::client
    end

    subgraph Frontend["Frontend Layer (React 18+)"]
        App["React App"]:::frontend
        click App "https://github.com/bdien/ludotheque/blob/master/src/webui/src/App.tsx"
        
        subgraph FrontendModules["Feature Modules"]
            UserMgmt["User Management"]:::frontend
            click UserMgmt "https://github.com/bdien/ludotheque/blob/master/src/webui/src/pages/user_list.tsx"
            InvMgmt["Inventory Management"]:::frontend
            click InvMgmt "https://github.com/bdien/ludotheque/blob/master/src/webui/src/pages/inventory.tsx"
            LoanMgmt["Loan Management"]:::frontend
            click LoanMgmt "https://github.com/bdien/ludotheque/blob/master/src/webui/src/pages/loan.tsx"
            DocMgmt["Document Management"]:::frontend
            click DocMgmt "https://github.com/bdien/ludotheque/blob/master/src/webui/src/pages/documents.tsx"
            Stats["Statistics/Reports"]:::frontend
            click Stats "https://github.com/bdien/ludotheque/blob/master/src/webui/src/pages/stats.tsx"
        end

        APIIntegration["API Integration"]:::frontend
        click APIIntegration "https://github.com/bdien/ludotheque/blob/master/src/webui/src/api/calls.ts"
        GlobalStore["Global Store"]:::frontend
        click GlobalStore "https://github.com/bdien/ludotheque/blob/master/src/webui/src/hooks/global_store.ts"
    end

    subgraph Backend["Backend Layer (FastAPI)"]
        APIServer["API Server"]:::backend
        click APIServer "https://github.com/bdien/ludotheque/blob/master/src/api/main.py"
        
        subgraph Services["Core Services"]
            Auth["Authentication/Users"]:::backend
            click Auth "https://github.com/bdien/ludotheque/blob/master/src/api/users.py"
            Bookings["Bookings"]:::backend
            click Bookings "https://github.com/bdien/ludotheque/blob/master/src/api/bookings.py"
            Items["Items/Inventory"]:::backend
            click Items "https://github.com/bdien/ludotheque/blob/master/src/api/items.py"
            Loans["Loans"]:::backend
            click Loans "https://github.com/bdien/ludotheque/blob/master/src/api/loans.py"
            Ledger["Ledger"]:::backend
            click Ledger "https://github.com/bdien/ludotheque/blob/master/src/api/ledger.py"
            Config["System Configuration"]:::backend
            click Config "https://github.com/bdien/ludotheque/blob/master/src/api/config.py"
        end

        EmailSystem["Email Templates"]:::backend
        click EmailSystem "https://github.com/bdien/ludotheque/blob/master/src/api/templates/email_retard.txt"
    end

    subgraph DataLayer["Data Layer"]
        DB[(Database)]:::database
        click DB "https://github.com/bdien/ludotheque/blob/master/src/api/pwmodels.py"
        Storage["File Storage"]:::storage
        click Storage "https://github.com/bdien/ludotheque/tree/master/storage/"
        GSheets["Google Sheets"]:::external
        click GSheets "https://github.com/bdien/ludotheque/blob/master/src/api/gsheets.py"
    end

    subgraph Infrastructure["Infrastructure"]
        Nginx["Nginx Proxy"]:::infra
        click Nginx "https://github.com/bdien/ludotheque/blob/master/setup/nginx.conf"
        Docker["Docker Container"]:::infra
        click Docker "https://github.com/bdien/ludotheque/tree/master/Dockerfile"
        FlyIO["Fly.io Deployment"]:::infra
        click FlyIO "https://github.com/bdien/ludotheque/blob/master/fly.toml"
    end

    Browser --> App
    App --> FrontendModules
    FrontendModules --> APIIntegration
    FrontendModules --> GlobalStore
    APIIntegration --> APIServer
    APIServer --> Services
    Services --> DB
    Services --> Storage
    Services --> GSheets
    Services --> EmailSystem
    APIServer --> Nginx
    Nginx --> Docker
    Docker --> FlyIO

    classDef client fill:#f9f,stroke:#333,stroke-width:2px
    classDef frontend fill:#a8d1ff,stroke:#333,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#333,stroke-width:1px
    classDef database fill:#ffdb58,stroke:#333,stroke-width:1px
    classDef storage fill:#ffa07a,stroke:#333,stroke-width:1px
    classDef external fill:#ff6b6b,stroke:#333,stroke-width:1px
    classDef infra fill:#c0c0c0,stroke:#333,stroke-width:1px
```
