# velopert/velofolio architecture

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

- Interactive diagram: https://gitdiagram.com/velopert/velofolio
- Repository: https://github.com/velopert/velofolio

## Overview

##### Project Type & Purpose
- This is a full-stack monorepo consisting of:
– A React-based Web client (“webapp”)
– A Fastify + TypeORM server (“server”)
– A data sync bot for ingesting historical prices
– A MariaDB database (containerized via Docker)

##### Top-Level Components
A. Client (Webapp)
- Hosted on Vercel
- React, TypeScript, Recoil, React Query, Emotion, ECharts
- Communicates over HTTPS to backend API
B. API Server
- Fastify framework with plugin architecture (JWT, search, user, close)
- TypeORM entities map to MariaDB tables
- Chart generation module (Chart.js) produces backtest images
- AWS S3 (or similar) for asset logo uploads
- Google OAuth integration (via Fastify plugin + “getGoogleProfile”)
- Fuse.js–powered search engine
C. Data Store
- MariaDB (deployed via Docker Compose in dev, AWS RDS in prod)
D. Sync Bot
- Node script (Syncbot) downloads tickers & historical data
- Writes data into MariaDB & asset/logo storage
E. External Services
- FinancialModelingPrep API (historical prices, sector weightings, profiles)
- Google OAuth endpoints
- AWS S3 (for uploaded assets)
- Vercel (for hosting Webapp)
- AWS EC2 / ECS / Lambda (for hosting API)

##### Interactions & Data Flows
1. End user → Webapp
- User interacts via browser → HTTPS
2. Webapp ↔ API Server
- REST endpoints under `/api/*`
- Request schemas validated (JSON Schema files under `src/schema`)
- Authenticated calls carry JWT tokens (plugin on server + client stores token)
3. API Server → MariaDB
- CRUD via TypeORM entities (e.g., User, Asset, Backtest)
4. API Server → External Finance API
- Historical prices, stock profiles, sector weightings
5. API Server → AWS S3
- Asset/logo uploads via `lib/aws/upload.ts`
6. Sync Bot → API Server libraries & Database
- Runs `yarn syncbot`, ingests CSV tickers, stores data
7. OAuth Flow
- Frontend: Google Sign-in button → redirects to Google
- Backend: receives token, calls Google API library → issues local JWT

##### Key Architectural Patterns & Design Principles
- Monorepo via Yarn workspaces: shared tooling, single CI/CD
- Plugin­based API server (Fastify plugins) for modular features
- Schema‐first validation (JSON schemas in `src/schema`)
- Entity‐driven data model (TypeORM)
- Separation of concerns: Sync bot vs. API server vs. Web client
- Infrastructure as code: Docker Compose for local DB; deploy configs for AWS & Vercel

##### Final Checklist
[ ] All main components represented with clear labels
[ ] Call out key technologies (React, Fastify, TypeORM, MariaDB, Fuse.js)
[ ] Validate with developers that each component and interaction is covered

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client (Webapp)" 
        Webapp["React Webapp"]:::client
    end

    subgraph "API Server" 
        Main["main.ts"]:::server
        ServerInit["Server.ts"]:::server
        Init["init.ts"]:::server
        Index["index.ts"]:::server
        subgraph "Plugins"
            JWT["jwtPlugin.ts"]:::server
            SearchP["searchPlugin.ts"]:::server
            UserP["userPlugin.ts"]:::server
            CloseP["closePlugin.ts"]:::server
        end
        subgraph "Routes"
            APIIndex["api/index.ts"]:::server
            Auth["auth/index.ts"]:::server
            Assets["assets/index.ts"]:::server
            Backtests["backtests/index.ts"]:::server
            Me["me/index.ts"]:::server
        end
        Schema["schema/"]:::server
        subgraph "Entities"
            Entities["*.ts"]:::server
        end
        JWTlib["jwt.ts"]:::server
        SearchEngine["SearchEngine.ts"]:::server
        Chart["generateBacktestChart.ts"]:::server
        S3["upload.ts"]:::server
        Google["getGoogleProfile.ts"]:::server
    end

    DB["MariaDB (Docker)"]:::db

    subgraph "Sync Bot" 
        SyncEntry["Syncbot.ts"]:::sync
        SyncIndex["index.ts"]:::sync
        subgraph "Sync Libs"
            DownloadLogo["downloadStockLogo.ts"]:::sync
            Treasury["getThreeMonthsTreasuryRate.ts"]:::sync
            Group["groupByMonth.ts"]:::sync
        end
        Tickers["tickers/"]:::sync
    end

    subgraph "External Services"
        FinModel["FinancialModelingPrep API"]:::external
        GoogleOAuth["Google OAuth"]:::external
        AWSs3["AWS S3"]:::external
        Vercel["Vercel"]:::external
        AWSHost["AWS EC2/ECS/Lambda"]:::external
    end

    Webapp -->|HTTPS REST| APIIndex
    Webapp -->|OAuth Redirect| GoogleOAuth
    APIIndex -->|CRUD via TypeORM| DB
    APIIndex -->|calls Finance API| FinModel
    APIIndex -->|uploads via S3 API| AWSs3
    SyncEntry -->|runs| SyncIndex
    SyncIndex --> DownloadLogo
    SyncIndex --> Treasury
    SyncIndex --> Group
    SyncIndex -->|writes data| DB
    SyncIndex -->|downloads data| FinModel
    SyncIndex -->|stores logos| AWSs3
    Main -->|initializes| ServerInit
    Main -->|calls| Init
    Init -->|registers| JWT
    Init -->|registers| SearchP
    Init -->|registers| UserP
    Init -->|registers| CloseP
    JWT --> JWTlib
    SearchP --> SearchEngine
    Chart --> AWSs3
    Google --> GoogleOAuth

    click Webapp "https://github.com/velopert/velofolio/tree/main/packages/webapp"
    click Main "https://github.com/velopert/velofolio/blob/main/packages/server/src/main.ts"
    click ServerInit "https://github.com/velopert/velofolio/blob/main/packages/server/src/Server.ts"
    click Init "https://github.com/velopert/velofolio/blob/main/packages/server/src/init.ts"
    click Index "https://github.com/velopert/velofolio/blob/main/packages/server/src/index.ts"
    click JWT "https://github.com/velopert/velofolio/blob/main/packages/server/src/plugins/jwtPlugin.ts"
    click SearchP "https://github.com/velopert/velofolio/blob/main/packages/server/src/plugins/searchPlugin.ts"
    click UserP "https://github.com/velopert/velofolio/blob/main/packages/server/src/plugins/userPlugin.ts"
    click CloseP "https://github.com/velopert/velofolio/blob/main/packages/server/src/plugins/closePlugin.ts"
    click APIIndex "https://github.com/velopert/velofolio/blob/main/packages/server/src/routes/api/index.ts"
    click Auth "https://github.com/velopert/velofolio/blob/main/packages/server/src/routes/api/auth/index.ts"
    click Assets "https://github.com/velopert/velofolio/blob/main/packages/server/src/routes/api/assets/index.ts"
    click Backtests "https://github.com/velopert/velofolio/blob/main/packages/server/src/routes/api/backtests/index.ts"
    click Me "https://github.com/velopert/velofolio/blob/main/packages/server/src/routes/api/me/index.ts"
    click Schema "https://github.com/velopert/velofolio/tree/main/packages/server/src/schema"
    click Entities "https://github.com/velopert/velofolio/tree/main/packages/server/src/entity"
    click JWTlib "https://github.com/velopert/velofolio/blob/main/packages/server/src/lib/token/jwt.ts"
    click SearchEngine "https://github.com/velopert/velofolio/blob/main/packages/server/src/search/SearchEngine.ts"
    click Chart "https://github.com/velopert/velofolio/blob/main/packages/server/src/lib/chart/generateBacktestChart.ts"
    click S3 "https://github.com/velopert/velofolio/blob/main/packages/server/src/lib/aws/upload.ts"
    click Google "https://github.com/velopert/velofolio/blob/main/packages/server/src/lib/google/getGoogleProfile.ts"
    click DB "https://github.com/velopert/velofolio/blob/main/docker/mariadb/docker-compose.yml"
    click SyncEntry "https://github.com/velopert/velofolio/blob/main/packages/server/src/sync/Syncbot.ts"
    click SyncIndex "https://github.com/velopert/velofolio/blob/main/packages/server/src/sync/index.ts"
    click DownloadLogo "https://github.com/velopert/velofolio/blob/main/packages/server/src/sync/lib/downloadStockLogo.ts"
    click Treasury "https://github.com/velopert/velofolio/blob/main/packages/server/src/sync/lib/getThreeMonthsTreasuryRate.ts"
    click Group "https://github.com/velopert/velofolio/blob/main/packages/server/src/sync/lib/groupByMonth.ts"
    click Tickers "https://github.com/velopert/velofolio/tree/main/packages/server/src/sync/tickers"
    click FinModel "https://github.com/velopert/velofolio/blob/main/packages/server/src/lib/finance-api/client.ts"
    click FinModel "https://github.com/velopert/velofolio/blob/main/packages/server/src/lib/finance-api/getHistoricalPrice.ts"
    click FinModel "https://github.com/velopert/velofolio/blob/main/packages/server/src/lib/finance-api/getSectorWeightings.ts"
    click FinModel "https://github.com/velopert/velofolio/blob/main/packages/server/src/lib/finance-api/getStockProfile.ts"

    classDef client fill:#cce5ff,stroke:#3399ff,color:#000
    classDef server fill:#d4edda,stroke:#28a745,color:#000
    classDef db fill:#e2e3e5,stroke:#6c757d,color:#000
    classDef sync fill:#fff3cd,stroke:#ffc107,color:#000
    classDef external fill:#ffe5b4,stroke:#ff8c00,color:#000
```
