# aperezcastagnino/tecina architecture

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

- Interactive diagram: https://gitdiagram.com/aperezcastagnino/tecina
- Repository: https://github.com/aperezcastagnino/tecina

## Overview

##### Main Components

- Frontend:
- Developed with TypeScript/JavaScript, located under the “frontend” folder.
- Contains assets (images, JSON level data, fonts, etc.), a structured scene system (boot, level1, main-menu, etc.), and configuration via Vite and Node.
- Likely acts as the client-side interface for a game or interactive application, rendering game scenes and handling client-side logic.

- Backend:
- Written in Python and organized under the “backend” folder.
- Exposes API endpoints (under the “src/api/v1” directory) with controllers (such as gemini_controller) and services (like gemini_service) to handle business logic.
- Contains configuration files (e.g., .env.example, config.py) and initialization scripts.
- Likely acts as the API layer for game logic, player state management, or data validation/aggregation.

- Infrastructure & Deployment:
- Dockerfiles are present for both frontend and backend alongside a docker-compose.yaml – indicating containerization and separate deployment of services.
- GitHub workflows under “.github/workflows” are used for CI/CD processes.
- There is also an nginx.conf in frontend hinting that a reverse proxy or static hosting server may be configured.

##### Component Relationships and Data Flow

- User Interaction:

- Frontend-to-Backend Communication:
- The frontend likely makes API calls to the backend via defined endpoints (for instance, routes under “/api/v1”).

- Internal Backend Structure:
- API Router (main_router.py) routes incoming requests.
- Controllers (like gemini_controller) receive and handle these requests.
- Services (like gemini_service) process the business logic.
- Schemas (found in “schemas/”) are used for data validation/serialization.
- Configuration and logging modules provide support functionality across the backend.
- As sub-components within the backend container.

- Deployment & Orchestration:

##### Architectural Patterns & Technologies

- Separation of Concerns:
- The clear division between frontend and backend.
- In the backend, the separation is further emphasized by organizing the API (controllers), business logic (services), and data schema layers.

- Containerization:
- Both services have dedicated Dockerfiles, showing that each can be built and deployed independently in isolated containers.

- Modern Web Tooling:
- Frontend uses Vite (vital for fast builds and module resolution) and standard convention for asset management in game development (assets, scenes, common UI components).

- API Design:
- The use of API versioning (e.g., “v1” in api/v1) indicates a foresight for potential evolution of the API.

## Diagram (Mermaid)

```mermaid
graph TD
    %% User Interaction
    Browser["User Browser"]:::client

    %% Frontend Subgraph
    subgraph "Frontend"
        UI["Game UI"]:::frontend
        Scenes["Scenes"]:::frontend
        CommonUI["Common UI Components"]:::frontend
        Assets["Assets"]:::frontend
        ViteConfig["Vite Config"]:::frontend
        TSConfig["TS Config"]:::frontend
        FrontendConfig["Frontend Config"]:::frontend
    end

    Browser -->|"loads"| UI
    UI -->|"manages"| Scenes
    UI -->|"manages"| CommonUI
    UI -->|"manages"| Assets
    UI -->|"uses"| ViteConfig
    UI -->|"uses"| TSConfig
    UI -->|"uses"| FrontendConfig

    %% Backend Subgraph
    subgraph "Backend API Service"
        MainApp["Main Application"]:::backend
        MainRouter["Main Router"]:::backend
        APIRouter["API Router"]:::backend
        GeminiController["Gemini Controller"]:::backend
        GeminiService["Gemini Service"]:::backend
        DataSchemas["Data Schemas"]:::backend
        Config["Config"]:::backend
        Logging["Logging"]:::backend
    end

    %% Frontend-to-Backend Communication
    UI -->|"API calls"| MainApp

    %% Backend Internal Flow
    MainApp -->|"routes"| MainRouter
    MainRouter -->|"forwards"| APIRouter
    APIRouter -->|"dispatches"| GeminiController
    GeminiController -->|"executes"| GeminiService
    GeminiController -->|"validates"| DataSchemas
    MainApp -->|"initializes"| Config
    MainApp -->|"logs via"| Logging

    %% Infrastructure & Deployment Subgraph
    subgraph "Infrastructure & Deployment"
        DockerCompose["Docker Compose"]:::infra
        FrontendDocker["Frontend Dockerfile"]:::infra
        BackendDocker["Backend Dockerfile"]:::infra
        CICD["CI/CD Pipeline"]:::infra
        Nginx["Reverse Proxy (nginx)"]:::infra
    end

    %% Infrastructure Relationships
    CICD -->|"triggers"| DockerCompose
    DockerCompose -->|"orchestrates"| FrontendDocker
    DockerCompose -->|"orchestrates"| BackendDocker
    Nginx -->|"serves"| UI

    %% Click Events for Frontend Components
    click Scenes "https://github.com/aperezcastagnino/tecina/tree/main/frontend/src/scenes"
    click CommonUI "https://github.com/aperezcastagnino/tecina/tree/main/frontend/src/common-ui"
    click Assets "https://github.com/aperezcastagnino/tecina/tree/main/frontend/src/assets"
    click ViteConfig "https://github.com/aperezcastagnino/tecina/blob/main/frontend/vite.config.ts"
    click TSConfig "https://github.com/aperezcastagnino/tecina/blob/main/frontend/tsconfig.json"
    click FrontendConfig "https://github.com/aperezcastagnino/tecina/blob/main/frontend/src/config/config.ts"

    %% Click Events for Backend Components
    click MainApp "https://github.com/aperezcastagnino/tecina/blob/main/backend/src/main.py"
    click MainRouter "https://github.com/aperezcastagnino/tecina/blob/main/backend/src/main_router.py"
    click APIRouter "https://github.com/aperezcastagnino/tecina/blob/main/backend/src/api/v1/router.py"
    click GeminiController "https://github.com/aperezcastagnino/tecina/tree/main/backend/src/api/v1/controllers"
    click GeminiService "https://github.com/aperezcastagnino/tecina/blob/main/backend/src/services/gemini_service.py"
    click DataSchemas "https://github.com/aperezcastagnino/tecina/tree/main/backend/src/schemas"
    click Config "https://github.com/aperezcastagnino/tecina/blob/main/backend/src/config.py"
    click Logging "https://github.com/aperezcastagnino/tecina/blob/main/backend/src/logging.py"

    %% Click Events for Infrastructure Components
    click FrontendDocker "https://github.com/aperezcastagnino/tecina/tree/main/frontend/Dockerfile"
    click BackendDocker "https://github.com/aperezcastagnino/tecina/tree/main/backend/Dockerfile"
    click DockerCompose "https://github.com/aperezcastagnino/tecina/blob/main/docker-compose.yaml"
    click CICD "https://github.com/aperezcastagnino/tecina/blob/main/.github/workflows/flows.yml"
    click Nginx "https://github.com/aperezcastagnino/tecina/blob/main/frontend/nginx.conf"

    %% Styles
    classDef client fill:#ffe6cc,stroke:#cc6600,stroke-width:2px;
    classDef frontend fill:#cce5ff,stroke:#3399ff,stroke-width:2px;
    classDef backend fill:#d5f5e3,stroke:#28a745,stroke-width:2px;
    classDef infra fill:#fff3cd,stroke:#ffc107,stroke-width:2px;
```
