# trevbook/pax-pal-2025 architecture

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

- Interactive diagram: https://gitdiagram.com/trevbook/pax-pal-2025
- Repository: https://github.com/trevbook/pax-pal-2025

## Overview

##### Project type and purpose
- It consists of:
- A React-based frontend (Vite build, served by Nginx).
- A Python backend (likely FastAPI or Flask given main.py, models.py, db.py) with Docker support.
- A database (used by the backend, set up via docker-compose).
- Data-exploration/ETL experiments in Jupyter notebooks (under experiments/).
- CI/CD pipelines (GitHub Actions, Cloud Run templates).

##### File structure
- Top-level:
- .github/ (CI/CD definitions, Cloud Run service templates)
- docker-compose.yml (local dev orchestration)
- backend/ (Python API, Dockerfile, models, utilities)
- frontend/ (React code, Dockerfile, Nginx config)
- experiments/ (notebooks for data scraping & prepping)
- Patterns: clear separation of concerns – frontend, backend, data-prep.
- Configs: GitHub workflows for building/pushing images; Cloud Run for deployments.

##### README for additional insights
- The README simply describes the goal: an exploratory webapp for games at PAX East 2025.

##### Detail
- Break each major service into subcomponents if needed (e.g., show Nginx ↔ static files ↔ SPA build artifacts).
- Ports (e.g., 80/443 for frontend, 8000 for backend).
- Environment differences (local via docker-compose vs. cloud via Cloud Run).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Browser["Web Browser"]:::client

    %% Frontend Service
    subgraph "Frontend Service" 
        direction TB
        FE_DOCKER["Dockerfile"] 
        FE_NGINX["nginx.conf"]
        FE_PKG["package.json"]
        FE_VITE["vite.config.js"]
        FE_SRC["src/"]
        FE_PUBLIC["public/"]
    end

    %% Backend Service
    subgraph "Backend Service"
        direction TB
        BE_DOCKER["Dockerfile"]
        BE_PYPROJECT["pyproject.toml"]
        BE_MAIN["main.py"]
        BE_MODELS["models.py"]
        BE_DB_FILE["db.py"]
        BE_SEARCH["search_utils.py"]
        BE_OAI["utils/openai.py"]
    end

    %% Database & Local Orchestration
    LocalCompose["docker-compose.yml"]:::config
    DB["Database"]:::db

    %% External Services
    OPENAI["OpenAI API"]:::external

    %% ETL Experiments
    subgraph "ETL Experiments"
        direction TB
        ETL_NOTE["experiments/notebooks/"]
        ETL_UTIL["experiments/utils/"]
        ETL_PY["experiments/pyproject.toml"]
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        CI_GHA[".github/workflows/build-push-images.yml"]
        CI_CR[".github/cloudrun/service.template.yaml"]
    end

    %% Connections
    Browser -->|"HTTP(S)"| FE_DOCKER
    FE_DOCKER --> FE_NGINX
    FE_NGINX --> FE_SRC
    FE_SRC --> FE_PUBLIC
    FE_PUBLIC --> BE_MAIN
    BE_MAIN -->|"SQL queries"| DB
    BE_MAIN -->|"calls OpenAI"| OPENAI
    ETL_NOTE -->|"populates"| DB
    ETL_UTIL --> DB
    LocalCompose --> DB
    CI_GHA --> CI_CR
    CI_CR --> DB

    %% Click Events - Frontend
    click FE_DOCKER "https://github.com/trevbook/pax-pal-2025/tree/main/frontend/Dockerfile"
    click FE_NGINX "https://github.com/trevbook/pax-pal-2025/blob/main/frontend/nginx.conf"
    click FE_PKG "https://github.com/trevbook/pax-pal-2025/blob/main/frontend/package.json"
    click FE_VITE "https://github.com/trevbook/pax-pal-2025/blob/main/frontend/vite.config.js"
    click FE_SRC "https://github.com/trevbook/pax-pal-2025/tree/main/frontend/src/"
    click FE_PUBLIC "https://github.com/trevbook/pax-pal-2025/tree/main/frontend/public/"

    %% Click Events - Backend
    click BE_DOCKER "https://github.com/trevbook/pax-pal-2025/tree/main/backend/Dockerfile"
    click BE_PYPROJECT "https://github.com/trevbook/pax-pal-2025/blob/main/backend/pyproject.toml"
    click BE_MAIN "https://github.com/trevbook/pax-pal-2025/blob/main/backend/main.py"
    click BE_MODELS "https://github.com/trevbook/pax-pal-2025/blob/main/backend/models.py"
    click BE_DB_FILE "https://github.com/trevbook/pax-pal-2025/blob/main/backend/db.py"
    click BE_SEARCH "https://github.com/trevbook/pax-pal-2025/blob/main/backend/search_utils.py"
    click BE_OAI "https://github.com/trevbook/pax-pal-2025/blob/main/backend/utils/openai.py"

    %% Click Events - Orchestration & Config
    click LocalCompose "https://github.com/trevbook/pax-pal-2025/blob/main/docker-compose.yml"

    %% Click Events - ETL
    click ETL_NOTE "https://github.com/trevbook/pax-pal-2025/tree/main/experiments/notebooks/"
    click ETL_UTIL "https://github.com/trevbook/pax-pal-2025/tree/main/experiments/utils/"
    click ETL_PY "https://github.com/trevbook/pax-pal-2025/blob/main/experiments/pyproject.toml"
    
    %% Click Events - CI/CD
    click CI_GHA "https://github.com/trevbook/pax-pal-2025/blob/main/.github/workflows/build-push-images.yml"
    click CI_CR "https://github.com/trevbook/pax-pal-2025/blob/main/.github/cloudrun/service.template.yaml"

    %% Styles
    classDef client fill:#cff,stroke:#006,stroke-width:1px
    classDef frontend fill:#ccf,stroke:#339,stroke-width:1px
    classDef backend fill:#cfc,stroke:#393,stroke-width:1px
    classDef db fill:#fcf,stroke:#939,stroke-width:1px
    classDef external fill:#eee,stroke:#666,stroke-width:1px,stroke-dasharray: 5 5
    classDef etl fill:#cff,stroke:#066,stroke-width:1px
    classDef ci fill:#fdd,stroke:#933,stroke-width:1px
    classDef config fill:#ffd,stroke:#aa0,stroke-width:1px
```
