# pydantic/connect4 architecture

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

- Interactive diagram: https://gitdiagram.com/pydantic/connect4
- Repository: https://github.com/pydantic/connect4

## Overview

##### Project type and purpose
- This is a full-stack “Connect4” demo application showcasing PydanticAI and Logfire.
- The codebase contains:
- A Python backend API and game logic under `/backend`
- A React/TypeScript frontend under `/frontend`
- A standalone Deno-based AI microservice under `/c4ai`
- Infrastructure definitions (Docker, CI, Compose)

##### File structure to spot architectural components
- Top-level:
- `frontend/` → Single-page app (Vite + React + TSX)
- `backend/` → Python API server, game engine, DB interface, schema
- `c4ai/` → Deno service providing AI moves (PydanticAI logic)
- `docker-compose.yml`, `Dockerfile` → Deployment orchestrator
- Config & automation:
- `.github/workflows/ci.yml` → CI pipeline
- `Makefile`, `render.yaml` → Dev & deploy scripts

##### Key insights from the README
- Instructions to run front and back in dev mode
- Live demo URL and project goal (“Demo of what PydanticAI and Logfire can do!”)

##### Main components
a. Frontend SPA (React + TypeScript)
b. Backend API server (Python/Flask or FastAPI style)
c. AI microservice (Deno + PydanticAI logic)
d. Database (SQL schema in `schema.sql`, likely SQLite/Postgres)
e. External monitoring/logging (Logfire)
f. CI/CD pipeline (GitHub Actions)
g. Container orchestration (Docker Compose)

##### Relationships and data flows
- Frontend ↔ Backend
- User actions (join game, place disc) → HTTP/JSON → `/api` endpoints in `backend/api.py`
- Backend returns game state, moves, validation
- Backend ↔ AI microservice
- For AI vs. AI or Human vs. AI games, backend calls Deno service endpoints (`c4ai/main.ts`)
- Backend ↔ Database
- Persist game history, sessions via `backend/db.py` using `schema.sql`
- Backend → Logfire
- Emit structured logs/events for monitoring and debugging
- CI/CD pipeline → Build & deploy Docker images for frontend, backend, AI service

##### Architectural patterns and design principles
- Clear separation of concerns:
- UI layer in `frontend/`
- Business logic and API in `backend/`
- AI logic extracted into a microservice in `c4ai/`
- Microservices pattern: decoupled AI service
- API-driven design: JSON over HTTP
- Containerization for environment consistency

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend UI" 
        direction TB
        F1["React SPA"]:::frontend
        F2["index.html"]:::frontend
        F3["App.tsx"]:::frontend
        F4["HomePage.tsx"]:::frontend
        F5["PlayerSelection.tsx"]:::frontend
        F6["HumanAIPlay.tsx"]:::frontend
        F7["AivsAiPlay.tsx"]:::frontend
        F8["GameBoard.tsx"]:::frontend
        F9["ai-service.ts"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Services" 
        direction TB
        B1["server.py"]:::backend
        B2["api.py"]:::backend
        B3["game.py"]:::backend
        B4["agent.py"]:::backend
        B5["c4model.py"]:::backend
        B6["demo_ai_vs_ai.py"]:::backend
        B7["db.py"]:::backend
        B8["schema.sql"]:::backend
    end

    %% AI Microservice
    subgraph "AI Microservice" 
        direction TB
        A1["main.ts"]:::ai
        A2["run.sh"]:::ai
        A3["deno.json"]:::ai
        A4["deno.lock"]:::ai
        A5["Dockerfile"]:::ai
    end

    %% Infrastructure & Infra Tools
    subgraph "Infrastructure" 
        direction TB
        I1["docker-compose.yml"]:::infra
        I2["Dockerfile"]:::infra
        I3[".github Actions CI"]:::infra
        I4["Makefile"]:::infra
        I5["render.yaml"]:::infra
        I6[(Postgres/SQLite DB)]:::infra
        I7["Logfire Monitoring"]:::infra
    end

    %% Connections
    F1 -->|HTTP/JSON| B2
    F3 -->|renders UI| F1
    B2 -->|calls rules| B3
    B2 -->|orchestrates AI| B4
    B4 -->|wraps model| B5
    B2 -->|persists| B7
    B7 -->|schema| B8
    B2 -->|logs events| I7
    B2 -->|HTTP/JSON| A1
    A1 -->|uses PydanticAI| A3
    A1 -->|lock config| A4
    I1 -->|orchestrates| F1
    I1 -->|orchestrates| B1
    I1 -->|orchestrates| A1
    I3 -->|build/test| I2
    I3 -->|trigger| I1
    B6 -->|demo AI game| B2
    B1 -->|entrypoint| B2
    B2 -->|connect| I6

    %% Click Events
    click F1 "https://github.com/pydantic/connect4/tree/main/frontend/"
    click F2 "https://github.com/pydantic/connect4/blob/main/frontend/index.html"
    click F3 "https://github.com/pydantic/connect4/blob/main/frontend/src/App.tsx"
    click F4 "https://github.com/pydantic/connect4/blob/main/frontend/src/HomePage.tsx"
    click F5 "https://github.com/pydantic/connect4/blob/main/frontend/src/PlayerSelection.tsx"
    click F6 "https://github.com/pydantic/connect4/blob/main/frontend/src/HumanAIPlay.tsx"
    click F7 "https://github.com/pydantic/connect4/blob/main/frontend/src/AivsAiPlay.tsx"
    click F8 "https://github.com/pydantic/connect4/blob/main/frontend/src/GameBoard.tsx"
    click F9 "https://github.com/pydantic/connect4/blob/main/frontend/src/ai-service.ts"
    click B1 "https://github.com/pydantic/connect4/blob/main/backend/server.py"
    click B2 "https://github.com/pydantic/connect4/blob/main/backend/api.py"
    click B3 "https://github.com/pydantic/connect4/blob/main/backend/game.py"
    click B4 "https://github.com/pydantic/connect4/blob/main/backend/agent.py"
    click B5 "https://github.com/pydantic/connect4/blob/main/backend/c4model.py"
    click B6 "https://github.com/pydantic/connect4/blob/main/backend/demo_ai_vs_ai.py"
    click B7 "https://github.com/pydantic/connect4/blob/main/backend/db.py"
    click B8 "https://github.com/pydantic/connect4/blob/main/backend/schema.sql"
    click A1 "https://github.com/pydantic/connect4/blob/main/c4ai/main.ts"
    click A2 "https://github.com/pydantic/connect4/blob/main/c4ai/run.sh"
    click A3 "https://github.com/pydantic/connect4/blob/main/c4ai/deno.json"
    click A4 "https://github.com/pydantic/connect4/blob/main/c4ai/deno.lock"
    click A5 "https://github.com/pydantic/connect4/tree/main/c4ai/Dockerfile"
    click I1 "https://github.com/pydantic/connect4/blob/main/docker-compose.yml"
    click I2 "https://github.com/pydantic/connect4/tree/main/Dockerfile"
    click I3 "https://github.com/pydantic/connect4/blob/main/.github/workflows/ci.yml"
    click I4 "https://github.com/pydantic/connect4/tree/main/Makefile"
    click I5 "https://github.com/pydantic/connect4/blob/main/render.yaml"

    %% Styles
    classDef frontend fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1
    classDef backend fill:#C8E6C9,stroke:#388E3C,color:#1B5E20
    classDef ai fill:#FFE0B2,stroke:#FB8C00,color:#E65100
    classDef infra fill:#E0E0E0,stroke:#9E9E9E,color:#424242
```
