# oscarhelmet/tradle architecture

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

- Interactive diagram: https://gitdiagram.com/oscarhelmet/tradle
- Repository: https://github.com/oscarhelmet/tradle

## Overview

##### Project Type and Purpose
- This is a full-stack web application combining:
– A React/TypeScript single-page frontend
– A Node.js/Express REST API backend
– A MongoDB database
– An external AI service (Google Gemini) for image analysis and insights
- Its goal is to let users register, log trades (manually or via AI image extraction), view analytics, and receive AI-powered reflections.

##### File Structure
- Top-level separation:
– “src” folder: frontend React app (components, pages, context, services/api)
– “server” folder: backend Express app (routes, services/gemini, models, middleware, config)
– “public” folder: static assets (index.html, manifest, robots.txt)
- Backend organizes code by concern:
– config/db.js for Mongo connection
– models/*.js for Mongoose schemas
– routes/*.js for REST endpoints
– services/gemini.js for AI API integration
– middleware/auth.js for JWT auth, upload.js for file handling
- Frontend organizes by feature:
– pages/ for routes (analysis, auth, journal, reflection, settings, dashboard)
– components/ for UI elements (charts, modals, layout, ui primitives)
– services/api/ApiService.ts for HTTP calls
– services/gemini/GeminiService.ts for any direct AI invocations (though these now go via backend)
– context/AuthContext.tsx for global auth state

##### Relationships and Data Flows
- User → Browser UI: input/trade management
- Browser → API: REST calls (login, register, CRUD trades, request analysis)
- API → MongoDB: queries and updates
- API → Gemini: image analysis, insight generation
- API → Browser: JSON responses with data or AI reflections

##### Architectural Patterns
- Monolithic backend following MVC-style separation (models, routes/controllers, services)
- Feature-driven frontend structure
- Separation of concerns: UI vs. API vs. data layer vs. external AI
- Stateless JWT authentication
- Service abstraction for AI integration
- Responsive, componentized UI with Tailwind CSS

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client: Frontend SPA"
        style ClientLayer fill:#D0E8FF,stroke:#333,stroke-width:1px
        Entry["Entry Point\npublic/index.html"]:::frontend
        SPA["React SPA"]:::frontend
        AuthCtx["AuthContext"]:::frontend
        ApiSvc["ApiService"]:::frontend
        GeminiSvc["GeminiService"]:::frontend
        subgraph "Pages"
            Analysis["Analysis Page"]:::frontend
            Login["Login Page"]:::frontend
            Register["Register Page"]:::frontend
            Dashboard["Dashboard Page"]:::frontend
            JournalList["Journal List Page"]:::frontend
            NewTrade["New Trade Page"]:::frontend
            EditTrade["Edit Trade Page"]:::frontend
            QuickAdd["Quick Add Page"]:::frontend
            TradeDetail["Trade Detail Page"]:::frontend
            Reflection["Reflection Page"]:::frontend
            Settings["Settings Page"]:::frontend
        end
        subgraph "Components"
            TradeChart["TradePerformanceChart"]:::frontend
            TradingStats["TradingStatistics"]:::frontend
            Layout["Layout"]:::frontend
            Navigation["Navigation"]:::frontend
            QuickAddModal["QuickAddModal"]:::frontend
            UIPrims["UI Primitives"]:::frontend
        end
    end

    %% Server Layer
    subgraph "Server: Express API"
        style ServerLayer fill:#D0FFD0,stroke:#333,stroke-width:1px
        API["Express API"]:::backend
        DBConfig["db.js"]:::backend
        subgraph "Routes"
            AuthRoute["auth.js"]:::backend
            TradesRoute["trades.js"]:::backend
            AnalysisRoute["analysis.js"]:::backend
            MetricsRoute["metrics.js"]:::backend
            ReflectionRoute["reflection.js"]:::backend
        end
        subgraph "Models"
            UserModel["User.js"]:::backend
            TradeModel["TradeEntry.js"]:::backend
            ReflectionModel["AIReflection.js"]:::backend
        end
        subgraph "Middleware"
            JWTAuth["auth.js"]:::backend
            Upload["upload.js"]:::backend
        end
        GeminiSrv["gemini.js"]:::backend
        EnvConfig[".env files"]:::config
        Deploy["deploy.sh & ecosystem.config.js"]:::config
    end

    %% Database Layer
    DB["MongoDB"]:::db

    %% External Service
    ExternalAI["Google Gemini API"]:::external

    %% Connections
    Entry --> SPA
    SPA --> AuthCtx
    SPA --> ApiSvc
    SPA --> GeminiSvc
    SPA --> Analysis
    SPA --> Login
    SPA --> Register
    SPA --> Dashboard
    SPA --> JournalList
    SPA --> NewTrade
    SPA --> EditTrade
    SPA --> QuickAdd
    SPA --> TradeDetail
    SPA --> Reflection
    SPA --> Settings
    SPA --> TradeChart
    SPA --> TradingStats
    SPA --> Layout
    SPA --> Navigation
    SPA --> QuickAddModal
    SPA --> UIPrims

    Analysis --> ApiSvc
    Login --> ApiSvc
    Register --> ApiSvc
    Dashboard --> ApiSvc
    JournalList --> ApiSvc
    NewTrade --> ApiSvc
    EditTrade --> ApiSvc
    QuickAdd --> ApiSvc
    TradeDetail --> ApiSvc
    Reflection --> ApiSvc
    Settings --> ApiSvc

    ApiSvc -->|HTTPS JSON| API
    GeminiSvc -->|HTTPS JSON| API
    API -->|Mongoose queries| DB
    API -->|REST/HTTP image analysis| ExternalAI
    API -->|JSON responses| ApiSvc

    DBConfig --> API
    AuthRoute --> API
    TradesRoute --> API
    AnalysisRoute --> API
    MetricsRoute --> API
    ReflectionRoute --> API
    UserModel --> API
    TradeModel --> API
    ReflectionModel --> API
    JWTAuth --> API
    Upload --> API
    GeminiSrv --> API
    EnvConfig --> API
    Deploy --> API

    %% Click Events
    click Entry "https://github.com/oscarhelmet/tradle/blob/main/public/index.html"
    click SPA "https://github.com/oscarhelmet/tradle/tree/main/src/"
    click AuthCtx "https://github.com/oscarhelmet/tradle/blob/main/src/context/AuthContext.tsx"
    click ApiSvc "https://github.com/oscarhelmet/tradle/blob/main/src/services/api/ApiService.ts"
    click GeminiSvc "https://github.com/oscarhelmet/tradle/blob/main/src/services/gemini/GeminiService.ts"
    click Analysis "https://github.com/oscarhelmet/tradle/blob/main/src/pages/analysis/Analysis.tsx"
    click Login "https://github.com/oscarhelmet/tradle/blob/main/src/pages/auth/Login.tsx"
    click Register "https://github.com/oscarhelmet/tradle/blob/main/src/pages/auth/Register.tsx"
    click Dashboard "https://github.com/oscarhelmet/tradle/blob/main/src/pages/dashboard/Dashboard.tsx"
    click JournalList "https://github.com/oscarhelmet/tradle/blob/main/src/pages/journal/Journal.tsx"
    click NewTrade "https://github.com/oscarhelmet/tradle/blob/main/src/pages/journal/NewTrade.tsx"
    click EditTrade "https://github.com/oscarhelmet/tradle/blob/main/src/pages/journal/EditTrade.tsx"
    click QuickAdd "https://github.com/oscarhelmet/tradle/blob/main/src/pages/journal/QuickAdd.tsx"
    click TradeDetail "https://github.com/oscarhelmet/tradle/blob/main/src/pages/journal/TradeDetail.tsx"
    click Reflection "https://github.com/oscarhelmet/tradle/blob/main/src/pages/reflection/ReflectionPage.tsx"
    click Settings "https://github.com/oscarhelmet/tradle/blob/main/src/pages/settings/Settings.tsx"
    click TradeChart "https://github.com/oscarhelmet/tradle/blob/main/src/components/charts/TradePerformanceChart.tsx"
    click TradingStats "https://github.com/oscarhelmet/tradle/blob/main/src/components/charts/TradingStatistics.tsx"
    click Layout "https://github.com/oscarhelmet/tradle/blob/main/src/components/layout/Layout.tsx"
    click Navigation "https://github.com/oscarhelmet/tradle/blob/main/src/components/layout/Navigation.tsx"
    click QuickAddModal "https://github.com/oscarhelmet/tradle/blob/main/src/components/modals/QuickAddModal.tsx"
    click UIPrims "https://github.com/oscarhelmet/tradle/tree/main/src/components/ui/"
    click API "https://github.com/oscarhelmet/tradle/blob/main/server/server.js"
    click DBConfig "https://github.com/oscarhelmet/tradle/blob/main/server/config/db.js"
    click UserModel "https://github.com/oscarhelmet/tradle/blob/main/server/models/User.js"
    click TradeModel "https://github.com/oscarhelmet/tradle/blob/main/server/models/TradeEntry.js"
    click ReflectionModel "https://github.com/oscarhelmet/tradle/blob/main/server/models/AIReflection.js"
    click AuthRoute "https://github.com/oscarhelmet/tradle/blob/main/server/routes/auth.js"
    click TradesRoute "https://github.com/oscarhelmet/tradle/blob/main/server/routes/trades.js"
    click AnalysisRoute "https://github.com/oscarhelmet/tradle/blob/main/server/routes/analysis.js"
    click MetricsRoute "https://github.com/oscarhelmet/tradle/blob/main/server/routes/metrics.js"
    click ReflectionRoute "https://github.com/oscarhelmet/tradle/blob/main/server/routes/reflection.js"
    click JWTAuth "https://github.com/oscarhelmet/tradle/blob/main/server/middleware/auth.js"
    click Upload "https://github.com/oscarhelmet/tradle/blob/main/server/middleware/upload.js"
    click GeminiSrv "https://github.com/oscarhelmet/tradle/blob/main/server/services/gemini.js"
    click EnvConfig "https://github.com/oscarhelmet/tradle/blob/main/.env.example"
    click Deploy "https://github.com/oscarhelmet/tradle/blob/main/deploy.sh"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef backend fill:#D0FFD0,stroke:#333,stroke-width:1px
    classDef db fill:#FFE5B4,stroke:#333,stroke-width:1px
    classDef external fill:#E2D0FF,stroke:#333,stroke-width:1px
    classDef config fill:#F0F0F0,stroke:#333,stroke-width:1px
```
