# gzukas/heropad architecture

> Architecture diagram of the GitHub repository gzukas/heropad, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gzukas/heropad
- Repository: https://github.com/gzukas/heropad

## Overview

##### Main Components

a) Frontend Layer (apps/web):
- Client Application (React)
- State Management (Jotai atoms)
- UI Components (Material UI)
- Routing (Tanstack Router)
- Internationalization (Lingui)
- Graph Visualization (Sigma.js/Graphology)
- Virtual Lists (Tanstack Virtual)

b) Backend Layer (apps/api):
- API Server (Fastify)
- tRPC Router
- Query Layer (Kysely)
- Input Validation (TypeBox)
- Avatar Generation (DiceBear)

c) Database Layer:
- PostgreSQL Database (Supabase)
- Migrations
- Search functionality

**[Client Layer]**
- ↕
**[Server Layer]**
- ↕
**[Database Layer]**

##### Component Relationships

- tRPC communication between frontend and backend
- Database queries from the backend
- State management flow in the frontend
- Avatar generation requests
- Search data flow
- Graph data processing pipeline

##### Detailed Component Breakdown

Frontend (apps/web):
**[React Application]**
- ↓
**[State Management]**
- Graph Atom
- Search Atoms
- Locale Atoms
- UI State Atoms
- ↓
**[UI Components]**
- Sociogram
- Search
- Hero Profile
- Awards List

Backend (apps/api):
**[Fastify Server]**
- ↓
**[tRPC Router]**
- Award Routes
- Hero Routes
- Graph Routes
- Search Routes
- ↓
**[Database Layer]**
- Kysely Queries
- Migrations

**[Database] → [Graph Data] → [Graphology] → [Sigma.js] → [Rendered Sociogram]**

**[Search Input] → [Debounced State] → [tRPC Query] → [Database Search] → [Results]**

##### Infrastructure Elements

Include:
- Supabase hosting
- Database migrations
- Build pipeline
- Testing infrastructure

##### Notes for Implementation

- Related components in containers
- Annotations for key features like virtualization and internationalization

- The typesafe nature of the stack (TypeScript throughout)
- The real-time interaction capabilities
- The separation of concerns between layers
- The state management flow
- The graph visualization pipeline

Remember to maintain a balance between detail and clarity, focusing on the architectural decisions that make Heropad unique, such as its graph visualization capabilities and social relationship mapping.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles
    classDef frontend fill:#3498db,stroke:#2980b9,color:white
    classDef backend fill:#2ecc71,stroke:#27ae60,color:white
    classDef database fill:#f1c40f,stroke:#f39c12,color:black
    classDef external fill:#9b59b6,stroke:#8e44ad,color:white
    classDef testing fill:#95a5a6,stroke:#7f8c8d,color:white

    %% Frontend Layer
    subgraph Frontend
        ReactApp["React Application"]
        StateManagement["State Management"]
        GraphVis["Graph Visualization"]
        SearchUI["Search System"]
        I18n["Internationalization"]
        Router["Routing System"]
        HeroComp["Hero Components"]
        FrontTest["Frontend Testing"]
    end

    %% Backend Layer
    subgraph Backend
        FastifyServer["Fastify Server"]
        TrpcRouter["tRPC Router"]
        AvatarGen["Avatar Generation"]
        ApiPlugins["API Plugins"]
        BackTest["Backend Testing"]
    end

    %% Database Layer
    subgraph Database
        DbLayer["Database Layer"]
        DbMigrations["Database Migrations"]
        Supabase[(Supabase PostgreSQL)]
    end

    %% Component Relationships
    ReactApp --> StateManagement
    ReactApp --> Router
    ReactApp --> I18n
    StateManagement --> GraphVis
    StateManagement --> SearchUI
    StateManagement --> HeroComp
    
    FastifyServer --> TrpcRouter
    FastifyServer --> AvatarGen
    FastifyServer --> ApiPlugins
    
    TrpcRouter --> DbLayer
    DbLayer --> Supabase
    DbMigrations --> Supabase
    
    SearchUI -.-> TrpcRouter
    GraphVis -.-> TrpcRouter
    HeroComp -.-> TrpcRouter
    
    FrontTest -.-> ReactApp
    BackTest -.-> FastifyServer
    
    %% External Service
    DiceBear["DiceBear API"]:::external
    AvatarGen --> DiceBear

    %% Click Events
    click ReactApp "https://github.com/gzukas/heropad/blob/main/apps/web/src/components/App.tsx"
    click StateManagement "https://github.com/gzukas/heropad/tree/main/apps/web/src/atoms/"
    click GraphVis "https://github.com/gzukas/heropad/tree/main/apps/web/src/components/Sociogram/"
    click SearchUI "https://github.com/gzukas/heropad/tree/main/apps/web/src/components/Search/"
    click I18n "https://github.com/gzukas/heropad/tree/main/apps/web/src/locales/"
    click Router "https://github.com/gzukas/heropad/blob/main/apps/web/src/router.ts"
    click FastifyServer "https://github.com/gzukas/heropad/blob/main/apps/api/src/server.ts"
    click TrpcRouter "https://github.com/gzukas/heropad/tree/main/apps/api/src/routes/trpc/"
    click AvatarGen "https://github.com/gzukas/heropad/blob/main/apps/api/src/routes/avatars.ts"
    click DbLayer "https://github.com/gzukas/heropad/tree/main/apps/api/src/database/"
    click DbMigrations "https://github.com/gzukas/heropad/tree/main/apps/api/supabase/migrations/"
    click HeroComp "https://github.com/gzukas/heropad/tree/main/apps/web/src/routes/(hero)/"
    click ApiPlugins "https://github.com/gzukas/heropad/tree/main/apps/api/src/plugins/"
    click FrontTest "https://github.com/gzukas/heropad/tree/main/apps/web/src/testing/"
    click BackTest "https://github.com/gzukas/heropad/tree/main/apps/api/test/"

    %% Style Applications
    class ReactApp,StateManagement,GraphVis,SearchUI,I18n,Router,HeroComp,FrontTest frontend
    class FastifyServer,TrpcRouter,AvatarGen,ApiPlugins,BackTest backend
    class DbLayer,DbMigrations,Supabase database
    class FrontTest,BackTest testing
```
