# wreckage0907/penny architecture

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

- Interactive diagram: https://gitdiagram.com/wreckage0907/penny
- Repository: https://github.com/wreckage0907/penny

## Overview

##### Project Type & Purpose
- Penny is a full-stack, cross-platform personal finance application.
- Frontend: Flutter mobile (iOS, Android, Web, Desktop).
- Backend: Python (FastAPI) API server.
- Purpose: deliver AI-powered courses, chat, practice questions, expense tracking, stock emulator, and news feeds.

##### File Structure Insights
- Top level:
- Assets, LICENSE, README.md
- backend/ – Python API service
- mobile/ – Flutter app (with android/, ios/, web/, linux/, macos/, windows/ subprojects)
- backend/
- main.py – FastAPI entrypoint
- routers/ – feature modules (chatbot, expenseTracker, questionGen, stockScrape, news, onboarding, profile, livestock)
- schema/ – Pydantic schemas per feature
- database/firebase_init.py – Firebase Admin SDK setup
- Dockerfile & render.yaml – containerization & deployment (Render.com)
- mobile/
- lib/Pages – UI screens matching backend features
- lib/Services/auth.dart – Firebase Auth integration
- lib/consts/backend_url.dart – API base URL
- pubspec.yaml – Flutter dependencies

##### README Highlights
- Tech stack: Flutter, Python, FastAPI, Firebase, Gemini AI, external stock & news APIs.
- Features powered by backend routes, Firebase, and Google’s Gemini.
- Deployment:
- backend runs in Docker on Render.com
- mobile built & deployed via Flutter SDK

a. Main Components
1. Mobile Client (Flutter App)
– UI Layers: Onboarding, Auth, Course, Chatbot, Practice, Expense Tracker, Stock Emulator, News
– Local persistence (e.g., secure storage for tokens)
2. Backend API (FastAPI)
– Routers (modular endpoints)
– Schema models (Pydantic)
– Firebase Admin (Auth & Firestore)
– External Service Integrations (Gemini API, Stock API, News API)
3. Database & Auth
– Firebase Authentication
– Firestore (user profiles, expenses, emulator portfolios)
4. External Services
– Gemini AI (RAG for chatbot & question generation)
– Financial News API
– Stock Price API
5. Deployment Infrastructure
– Docker container (backend)
– Render.com or similar PaaS

b. Relationships & Data Flows
– Mobile → Backend: HTTPS (REST) calls to routers
– Backend → Firebase: Admin SDK calls for auth, read/write Firestore
– Backend → Gemini AI / Stock / News APIs: HTTP requests, responses processed & returned
– Backend → Mobile: JSON responses (data, chat replies, questions, price data)
– Mobile: renders UI, stores tokens, sends user input & receives updates

c. Architectural Patterns
– Modular Monolith (FastAPI routers isolate feature logic)
– Separation of Concerns:
- Authentication (Firebase Auth)
- Business Logic (each router & service)
- Data Layer (schema + Firestore)
– RAG Pattern for chatbot & questionGen (vector store or document fetch + LLM calls)

d. Key Technologies & Frameworks
– Flutter / Dart
– FastAPI / Python 3.x
– Firebase (Auth, Firestore)
– Gemini AI API
– Docker, render.yaml (Render.com)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Mobile Layer
    subgraph "Mobile Client (Flutter App)"
        direction TB
        MobileApp["Flutter App"]:::frontend
        FlutterMain["main.dart"]:::frontend
        OnboardingUI["Onboarding Page"]:::frontend
        AuthServiceFlutter["Auth Service"]:::frontend
        APIUrlConst["API Base URL"]:::frontend
        CourseUI["Course Module UI"]:::frontend
        ChatbotUI["Chatbot UI Page"]:::frontend
        PracticeUI["Practice Questions UI"]:::frontend
        ExpenseUI["Expense Tracker UI"]:::frontend
        StockUI["Stock Emulator UI"]:::frontend
        MobileApp -->|uses| FlutterMain
        FlutterMain -->|navigates to| OnboardingUI
        FlutterMain -->|navigates to| CourseUI
        FlutterMain -->|navigates to| ChatbotUI
        FlutterMain -->|navigates to| PracticeUI
        FlutterMain -->|navigates to| ExpenseUI
        FlutterMain -->|navigates to| StockUI
        FlutterMain -->|initializes| AuthServiceFlutter
        FlutterMain -->|reads| APIUrlConst
    end

    %% Backend Layer
    subgraph "Backend Service (FastAPI)" 
        direction TB
        APIEntry["FastAPI Entrypoint"]:::backend
        FirebaseInit["Firebase Admin Init"]:::backend
        subgraph "Routers & Schemas"
            direction TB
            ChatbotRouter["Chatbot Router"]:::backend
            ExpenseRouter["Expense Tracker Router"]:::backend
            QuestionRouter["QuestionGen Router"]:::backend
            StockRouter["Stock Data Router"]:::backend
            StockScrapeRouter["Stock Scrape Router"]:::backend
            OnboardingRouter["Onboarding Router"]:::backend
            ProfileRouter["Profile Router"]:::backend
            LivestockRouter["Livestock Router"]:::backend
            FileRouter["File Handling Router"]:::backend
            SchemasDir["Pydantic Schemas"]:::backend
            NewsIntegration["External News Module"]:::backend
        end
        APIEntry -->|routes to| ChatbotRouter
        APIEntry -->|routes to| ExpenseRouter
        APIEntry -->|routes to| QuestionRouter
        APIEntry -->|routes to| StockRouter
        APIEntry -->|routes to| StockScrapeRouter
        APIEntry -->|routes to| OnboardingRouter
        APIEntry -->|routes to| ProfileRouter
        APIEntry -->|routes to| LivestockRouter
        APIEntry -->|routes to| FileRouter
        APIEntry -->|loads| FirebaseInit
        ChatbotRouter -->|uses schemas| SchemasDir
        ExpenseRouter -->|uses schemas| SchemasDir
        QuestionRouter -->|uses schemas| SchemasDir
        StockRouter -->|uses schemas| SchemasDir
        StockScrapeRouter -->|uses schemas| SchemasDir
        OnboardingRouter -->|uses schemas| SchemasDir
        ProfileRouter -->|uses schemas| SchemasDir
        LivestockRouter -->|uses schemas| SchemasDir
        FileRouter -->|uses schemas| SchemasDir
        NewsIntegration -->|integrates| NewsAPI
    end

    %% Data & Auth Layer
    subgraph "Firebase Services"
        direction TB
        FirebaseAuth["Firebase Auth"]:::database
        Firestore["Firestore DB"]:::database
        FirebaseInit -->|auth & db| FirebaseAuth
        FirebaseInit -->|auth & db| Firestore
        ChatbotRouter -->|read/write| Firestore
        ExpenseRouter -->|read/write| Firestore
        ProfileRouter -->|read/write| Firestore
    end

    %% External Services Layer
    subgraph "External Services"
        direction TB
        GeminiAPI["Gemini AI API"]:::external
        StockAPI["Stock Price API"]:::external
        NewsAPI["News API"]:::external
        QuestionRouter -->|calls| GeminiAPI
        ChatbotRouter -->|calls| GeminiAPI
        StockRouter -->|calls| StockAPI
        NewsIntegration -->|calls| NewsAPI
    end

    %% Deployment Layer
    subgraph "Deployment"
        direction TB
        DockerContainer["Docker Container"]:::infrastructure
        RenderPlatform["Render.com (PaaS)"]:::infrastructure
        Dockerfile["Backend Dockerfile"]:::infrastructure
        RenderYamlBackend["backend/render.yaml"]:::infrastructure
        RenderYamlTop["render.yaml"]:::infrastructure
        DockerContainer -->|config| Dockerfile
        DockerContainer -->|deploy| RenderPlatform
        RenderPlatform -->|uses| RenderYamlBackend
        RenderPlatform -->|uses| RenderYamlTop
        APIEntry -->|runs in| DockerContainer
    end

    %% Mobile to Backend Interaction
    MobileApp -->|HTTPS REST| APIEntry

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085;
    classDef backend fill:#d4edda,stroke:#155724,color:#155724;
    classDef database fill:#fff3cd,stroke:#856404,color:#856404;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef infrastructure fill:#d1ecf1,stroke:#0c5460,color:#0c5460;

    %% Click events
    click MobileApp "https://github.com/wreckage0907/penny/tree/main/mobile/"
    click OnboardingUI "https://github.com/wreckage0907/penny/blob/main/mobile/lib/Pages/home/onboarding_page.dart"
    click AuthServiceFlutter "https://github.com/wreckage0907/penny/blob/main/mobile/lib/Services/auth.dart"
    click APIUrlConst "https://github.com/wreckage0907/penny/blob/main/mobile/lib/consts/backend_url.dart"
    click CourseUI "https://github.com/wreckage0907/penny/tree/main/mobile/lib/Pages/coursePage/"
    click ChatbotUI "https://github.com/wreckage0907/penny/blob/main/mobile/lib/Pages/chatbot/chatbot_page.dart"
    click PracticeUI "https://github.com/wreckage0907/penny/tree/main/mobile/lib/Pages/practice/"
    click ExpenseUI "https://github.com/wreckage0907/penny/tree/main/mobile/lib/Pages/expenseTracker/"
    click StockUI "https://github.com/wreckage0907/penny/tree/main/mobile/lib/Pages/stocks/"
    click FlutterMain "https://github.com/wreckage0907/penny/blob/main/mobile/lib/main.dart"
    click APIEntry "https://github.com/wreckage0907/penny/blob/main/backend/main.py"
    click FirebaseInit "https://github.com/wreckage0907/penny/blob/main/backend/database/firebase_init.py"
    click ChatbotRouter "https://github.com/wreckage0907/penny/blob/main/backend/routers/chatbot.py"
    click ExpenseRouter "https://github.com/wreckage0907/penny/blob/main/backend/routers/expenseTracker.py"
    click QuestionRouter "https://github.com/wreckage0907/penny/blob/main/backend/routers/questionGen.py"
    click StockRouter "https://github.com/wreckage0907/penny/blob/main/backend/routers/stock.py"
    click StockScrapeRouter "https://github.com/wreckage0907/penny/blob/main/backend/routers/stockScrape.py"
    click OnboardingRouter "https://github.com/wreckage0907/penny/blob/main/backend/routers/onboarding.py"
    click ProfileRouter "https://github.com/wreckage0907/penny/blob/main/backend/routers/profile.py"
    click LivestockRouter "https://github.com/wreckage0907/penny/blob/main/backend/routers/livestock.py"
    click FileRouter "https://github.com/wreckage0907/penny/blob/main/backend/routers/file.py"
    click NewsIntegration "https://github.com/wreckage0907/penny/blob/main/backend/news_api.py"
    click SchemasDir "https://github.com/wreckage0907/penny/tree/main/backend/schema/"
    click Dockerfile "https://github.com/wreckage0907/penny/tree/main/backend/Dockerfile"
    click RenderYamlBackend "https://github.com/wreckage0907/penny/blob/main/backend/render.yaml"
    click RenderYamlTop "https://github.com/wreckage0907/penny/blob/main/render.yaml"
```
