# usernanni/placar architecture

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

- Interactive diagram: https://gitdiagram.com/usernanni/placar
- Repository: https://github.com/usernanni/placar

## Overview

##### Project type and purpose
- This is a full-stack, real-time scoreboard WebApplication for the “Olimpíada de História Militar e Aeronáutica.”
- Frontend: React + TypeScript SPA built with Vite, React Router, Chakra-UI and SASS.
- Backend: PocketBase (embedded Go-based DB + REST/API server) running in Docker on a VM (Fly.io).
- Deployment: frontend hosted via AWS Amplify (connected to GitHub), backend in a Docker container on Fly.io (or local Docker for LAN mode).

##### File structure to infer architectural layers
- src/components & src/routes → UI/Views layer (cards, header/footer, pages like Home, Placar).
- src/service → Service layer (pocketBase.tsx: client for REST calls; useParticipante.tsx: hooks for data fetching/business logic).
- index.html, Vite config & public/ → Build/static-asset layer.
- package.json, tsconfig → Tooling/configuration layer.

##### README for deployment/runtime context
- Initially ran locally with Docker-based PocketBase, port exposed on LAN for projector.
- Now: frontend pipeline on AWS Amplify (GitHub-driven CI/CD), public Landing Page + “/placar” routes, real-time projections at 1920×1080 viewport.

##### Main components
a. Client Browser (Projector or User device)
- Runs the React SPA (served as static assets)
b. CI/CD Pipeline
- GitHub repo + GitHub Actions (or AWS Amplify build triggers) → Vite build → deploy to AWS Amplify (S3 + CloudFront)
c. Frontend Hosting
- AWS Amplify (Static Web Hosting + CDN)
d. PocketBase Backend
- Docker container on Fly.io VM (or Docker locally for LAN mode)
- Exposes REST API / real-time endpoints, stores data in embedded DB
e. Data Storage
- SQLite (inside PocketBase)
f. Optional Local Mode
- Developer laptop running Docker & PocketBase, direct LAN access

##### Relationships & data flow
1. Developer pushes to GitHub → triggers CI/CD on AWS Amplify → Vite builds static bundle → deploy.
2. Client’s browser loads SPA from CDN (AWS Amplify).
3. SPA UI (components/routes) calls service layer (pocketBase.tsx) → REST/WebSocket requests to PocketBase API.
4. PocketBase processes requests, updates/fetches from embedded DB → returns JSON responses.
5. Service hooks (useParticipante) update React state → UI re-renders in real time.

##### Architectural patterns & principles
- SPA with clear separation:
- Presentation Layer (React components & routes)
- Service/Data Layer (client wrappers, hooks)
- Domain Layer (models, content)
- Stateless front-end, back-end as a BaaS (Backend-as-a-Service)
- CI/CD pipeline for automated builds and deployments
- Responsive design locked to 1920×1080 for projector mode

##### Technologies & frameworks
- React, React Router DOM, Chakra-UI, SASS
- TypeScript, Vite
- PocketBase (Docker)
- AWS Amplify (Static Hosting, CDN)
- GitHub (source control, CI/CD trigger)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CI/CD & Repo
    subgraph "CI/CD & Repo"
        GH["GitHub Repo + CI/CD"]:::infra
        Workflows[".github/workflows/main.yaml"]:::infra
        Package["package.json & package-lock.json"]:::infra
        TSConfig["tsconfig.json & tsconfig.node.json"]:::infra
    end

    %% Hosting
    subgraph "Hosting (Infra)"
        AWS["AWS Amplify\n(Static Hosting + CDN)"]:::infra
    end

    %% Client Browser and SPA
    subgraph "Client Browser"
        Browser["Client Browser\n(React SPA)"]:::frontend
    end

    subgraph "SPA Structure"
        Entry["index.html"]:::frontend
        Boot["src/main.tsx"]:::frontend
        App["src/App.tsx"]:::frontend

        subgraph "Presentation Layer"
            Home["src/routes/Home.tsx"]:::frontend
            HomeSCSS["src/routes/Home.scss"]:::frontend
            Placar["src/routes/Placar.tsx"]:::frontend
            PlacarSCSS["src/routes/Placar.scss"]:::frontend
            Final["src/routes/PlacarFinal-projecao.tsx"]:::frontend
            Inter["src/routes/PlacarIntermediario-projecao.tsx"]:::frontend
            Error["src/routes/ErrorPage.tsx"]:::frontend
            cardF["src/components/cardFinal.tsx"]:::frontend
            cardI["src/components/cardIntermediario.tsx"]:::frontend
            cardT["src/components/cardTotal.tsx"]:::frontend
            Header["src/components/header.tsx"]:::frontend
            Footer["src/components/footer.tsx"]:::frontend
            Toggle["src/components/colorModeToggle.tsx"]:::frontend
        end

        subgraph "Domain Layer"
            Models["src/domain/models.tsx"]:::frontend
            Content["src/content/text.tsx"]:::frontend
        end

        subgraph "Service Layer"
            PBClient["src/service/pocketBase.tsx"]:::frontend
            Hooks["src/service/useParticipante.tsx"]:::frontend
        end

        subgraph "Static Assets & Build Config"
            Public["public/"]:::infra
            ViteConfig["vite.config.ts"]:::infra
            ViteEnv["src/vite-env.d.ts"]:::infra
        end
    end

    %% Backend & Data
    subgraph "Backend"
        PB["PocketBase Docker Container"]:::backend
        DB["SQLite (embedded DB)"]:::backend
    end

    %% Optional Local Mode
    subgraph "Local Mode (Optional)"
        Local["Local Docker & PocketBase"]:::infra
    end

    %% Connections
    GH -->|"push / build trigger"| AWS
    AWS -->|"HTTPS GET static assets"| Browser
    Browser -->|loads| Entry
    Entry --> Boot
    Boot --> App
    App -->|"renders UI"| Home
    App --> Models
    App --> PBClient
    Home --> PBClient
    Placar --> PBClient
    Final --> PBClient
    Inter --> PBClient
    Error --> PBClient
    cardF --> PBClient
    cardI --> PBClient
    cardT --> PBClient
    Header --> PBClient
    Footer --> PBClient
    Toggle --> PBClient
    PBClient -->|"REST / WebSocket calls"| PB
    PB -->|"DB read/write"| DB
    Local --> PB

    %% Click events
    click Entry "https://github.com/usernanni/placar/blob/main/index.html"
    click Boot "https://github.com/usernanni/placar/blob/main/src/main.tsx"
    click App "https://github.com/usernanni/placar/blob/main/src/App.tsx"
    click Home "https://github.com/usernanni/placar/blob/main/src/routes/Home.tsx"
    click HomeSCSS "https://github.com/usernanni/placar/blob/main/src/routes/Home.scss"
    click Placar "https://github.com/usernanni/placar/blob/main/src/routes/Placar.tsx"
    click PlacarSCSS "https://github.com/usernanni/placar/blob/main/src/routes/Placar.scss"
    click Final "https://github.com/usernanni/placar/blob/main/src/routes/PlacarFinal-projecao.tsx"
    click Inter "https://github.com/usernanni/placar/blob/main/src/routes/PlacarIntermediario-projecao.tsx"
    click Error "https://github.com/usernanni/placar/blob/main/src/routes/ErrorPage.tsx"
    click cardF "https://github.com/usernanni/placar/blob/main/src/components/cardFinal.tsx"
    click cardI "https://github.com/usernanni/placar/blob/main/src/components/cardIntermediario.tsx"
    click cardT "https://github.com/usernanni/placar/blob/main/src/components/cardTotal.tsx"
    click Header "https://github.com/usernanni/placar/blob/main/src/components/header.tsx"
    click Footer "https://github.com/usernanni/placar/blob/main/src/components/footer.tsx"
    click Toggle "https://github.com/usernanni/placar/blob/main/src/components/colorModeToggle.tsx"
    click Models "https://github.com/usernanni/placar/blob/main/src/domain/models.tsx"
    click Content "https://github.com/usernanni/placar/blob/main/src/content/text.tsx"
    click PBClient "https://github.com/usernanni/placar/blob/main/src/service/pocketBase.tsx"
    click Hooks "https://github.com/usernanni/placar/blob/main/src/service/useParticipante.tsx"
    click Public "https://github.com/usernanni/placar/tree/main/public/"
    click ViteConfig "https://github.com/usernanni/placar/blob/main/vite.config.ts"
    click ViteEnv "https://github.com/usernanni/placar/blob/main/src/vite-env.d.ts"
    click Package "https://github.com/usernanni/placar/blob/main/package.json"
    click Workflows "https://github.com/usernanni/placar/blob/main/.github/workflows/main.yaml"
    click TSConfig "https://github.com/usernanni/placar/blob/main/tsconfig.json"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef backend fill:#FFD8A8,stroke:#d97706,stroke-width:1px
    classDef infra fill:#C8FACC,stroke:#027a48,stroke-width:1px
```
