# alexterrand/tarot architecture

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

- Interactive diagram: https://gitdiagram.com/alexterrand/tarot
- Repository: https://github.com/alexterrand/tarot

## Overview

##### Project Type and Purpose
- This is a full-stack application—a digital version of a traditional French Tarot game.
- The frontend is built in Flutter, providing the user interface.
- The backend uses FastAPI to expose RESTful endpoints and includes a dedicated, standalone module (tarot_logic) encapsulating the game’s rules and mechanics.
- Docker configuration files indicate containerized deployment and integration with CI/CD pipelines (as shown by the .github/workflows).

##### Analyzing the File Structure
- At the top level, you have directories for backend, frontend, Docker, and configuration files (like .github and .gitignore).
- The backend directory contains:
- app/: Houses the API endpoints (api/endpoints.py), core configuration (core/config.py), main FastAPI app (app/main.py), models, and services to handle game operations.
- tarot_logic/: A self-contained module with components for card, deck, game state, player logic, and game rules; this clearly represents the business logic.
- tests/: Tests for both the API and tarot logic—an important component to note as it reinforces the architectural quality through automated testing.
- The frontend directory contains the Flutter application code (main.dart and associated libraries/configuration).

##### Detail
a. Main Components to Include:
- Frontend (Flutter):
- As the client UI that handles user interactions.
- Backend API (Python with FastAPI):
- This is where the HTTP requests are received and routed, with key files like app/main.py and API endpoints.
- Game Logic Module (tarot_logic):
- This as a distinct module/library that the FastAPI server calls for processing game rules.
- Supporting Components:
- “Models & Services”: These can be shown within the FastAPI server to denote domain models (like game models) and business logic layers (game services).
- “Tests”: Indicate a testing layer covering both API endpoints and the game logic.
- “Docker Deployment”: Show docker containers (possibly a backend container and, if applicable, a container for the frontend or any other service) managed via docker-compose.
- “CI/CD Pipeline”: Optionally include a reference (e.g., GitHub Actions) that ensures code quality and deployment.

b. Relationships and Data Flow:
- Internal connection between Models/Services and the API endpoints.

c. Architectural Patterns and Design Principles:
- A separation-of-concerns design:
- The Flutter frontend strictly handles UI and user interactions.
- The backend separates API handling from game business logic (tarot_logic) and domain modeling (models).
- Clearly delineate configuration and deployment aspects (via Docker and GitHub workflows).

d. Technologies to Highlight:
- Flutter for the frontend UI.
- Python, FastAPI for the backend API.
- Uvicorn (as the ASGI server for FastAPI).
- Docker and docker-compose for containerization.
- Testing frameworks like pytest for backend testing.
- CI/CD tools integrated via GitHub Actions as shown in the .github/workflows directory.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        FE("Flutter App"):::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        BE("FastAPI Server"):::backend
        FEEndpoints("API Endpoints"):::backend
        CoreCfg("Core Configuration"):::backend
        Models("Models"):::backendModel
        GameService("Game Service"):::backendModel
    end

    %% Business Logic Module
    subgraph "Business Logic"
        Tar("Tarot Game Logic Module"):::logic
    end

    %% Testing Layer
    subgraph "Testing"
        Tests("Testing Suite"):::testing
    end

    %% Deployment Layer
    subgraph "Deployment"
        subgraph "Docker Deployment"
            D1("Backend Dockerfile"):::dockerfile
            D2("Docker Compose"):::dockercompose
        end
        CI("CI/CD Pipeline"):::pipeline
    end

    %% Connections
    FE -->|"HTTP_API_Request"| BE
    BE -->|"routes_to"| FEEndpoints
    FEEndpoints -->|"uses"| CoreCfg
    FEEndpoints -->|"invokes"_Models| Models
    FEEndpoints -->|"invokes"_Service| GameService
    BE -->|"calls"| Tar
    CI -->|"deploys_to"| D2
    D2 -->|"runs"| BE

    %% Styles
    classDef frontend fill:#f9e79f,stroke:#f39c12,stroke-width:2px;
    classDef backend fill:#aed6f1,stroke:#2980b9,stroke-width:2px;
    classDef backendModel fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef logic fill:#fcf3cf,stroke:#f1c40f,stroke-width:2px;
    classDef testing fill:#d7bde2,stroke:#8e44ad,stroke-width:2px;
    classDef pipeline fill:#a9dfbf,stroke:#27ae60,stroke-width:2px;
    classDef dockerfile fill:#fad7a0,stroke:#e67e22,stroke-width:2px;
    classDef dockercompose fill:#fad7a0,stroke:#e67e22,stroke-width:2px;

    %% Click Events
    click FE "https://github.com/alexterrand/tarot/blob/master/frontend/lib/main.dart"
    click BE "https://github.com/alexterrand/tarot/blob/master/backend/app/main.py"
    click FEEndpoints "https://github.com/alexterrand/tarot/blob/master/backend/app/api/endpoints.py"
    click CoreCfg "https://github.com/alexterrand/tarot/blob/master/backend/app/core/config.py"
    click Models "https://github.com/alexterrand/tarot/blob/master/backend/app/models/game.py"
    click GameService "https://github.com/alexterrand/tarot/blob/master/backend/app/services/game_service.py"
    click Tar "https://github.com/alexterrand/tarot/tree/master/backend/tarot_logic/"
    click Tests "https://github.com/alexterrand/tarot/tree/master/backend/tests/"
    click D1 "https://github.com/alexterrand/tarot/tree/master/docker/backend/Dockerfile"
    click D2 "https://github.com/alexterrand/tarot/blob/master/docker/docker-compose.yml"
    click CI "https://github.com/alexterrand/tarot/blob/master/.github/workflows/ci.yml"
```
