# budgetbuddyde/budgetbuddyde architecture

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

- Interactive diagram: https://gitdiagram.com/budgetbuddyde/budgetbuddyde
- Repository: https://github.com/budgetbuddyde/budgetbuddyde

## Overview

##### Main Components
- Frontend Applications:
- Webapp (apps/webapp): This is the main ReactJS-based application responsible for the core user interface. It contains routes, components (e.g., charts, forms, tables), state management for features like stock tracking, budgeting, and subscriptions.
- Website (apps/website): This is the public-facing website providing information such as privacy policies, terms of service, and general repository info.
- Documentation (apps/documentation): This uses VitePress and Docker – it aggregates project documentation and guides.
- Backend Services (Microservices):
- Auth Service (services/auth-service): Manages user authentication and related middleware.
- Mail Service (services/mail-service): Handles email functionality including sending newsletters and report emails.
- PocketBase (services/pocketbase): Acts as a core backend service, likely providing a lightweight database and API endpoints.
- Stock Service (services/stock-service): Manages stock-related functionalities such as tracking, caching, and reporting on investments.
- Shared Packages:
- Types (packages/types): Contains type definitions and interfaces used across the entire project.
- Utils (packages/utils): Provides reusable utilities (e.g., logger and helper functions) that are shared between apps and services.
- CI/CD and Configuration:
- CI Folder (ci/): Contains pipelines and scripts (e.g., Concourse pipelines and GitHub Actions) for automating builds, tests, and deployments.
- Config Files (in projects at root and under config/ folders): Docker configuration, environment variables, and compose files that support local and deployment environments.

##### Relationships and Interactions
- The frontend applications (webapp and website) interact with the backend services via HTTP/REST API calls. They most likely use standardized API endpoints defined by shared interfaces (from the types package).
- The auth-service, mail-service, pocketbase, and stock-service each run as independent services (potentially in containers) and communicate with the frontends directly or through an API gateway.
- Shared packages (types and utils) ensure consistency between the frontend and backend components.
- CI pipelines and configuration files facilitate continuous integration and orchestrated deployments (using Docker and docker-compose).

##### Architectural Patterns & Design Principles
- Microservices Architecture: The backend is split into distinct services (auth, mail, stock, etc.), enabling independent development, scalability, and deployment.
- Separation of Concerns: Frontend UI, backend business logic, and shared utilities are organized into separate directories and packages.
- Reusability and Modularity: Utilizing shared types and utilities promotes consistency across services and applications.
- Containerization: Dockerfiles in multiple folders (e.g., in apps/documentation, apps/webapp, services/*) indicate containerized deployment.
- CI/CD: Dedicated CI pipelines (in the ci directory) illustrate automated build/test/deploy processes.

##### Technologies & Frameworks
- ReactJS, Next.js, and VitePress for frontend applications.
- Node.js/TypeScript for many of the backend services (especially auth-service and mail-service).
- Go (for PocketBase and possibly parts of the stock-service) as indicated by files like main.go in the pocketbase service.
- Docker for containerization and deployment.
- CI/CD tools integrated via GitHub Actions and Concourse pipelines.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI/CD and Configuration
    CICD["CI/CD & Config"]:::cicd

    %% Frontend Applications Subgraph
    subgraph "Frontend Applications"
        WEBAPP["BudgetBuddy Webapp"]:::frontend
        WEBSITE["BudgetBuddy Website"]:::frontend
        DOCS["Documentation App"]:::frontend
    end

    %% Backend Microservices Subgraph
    subgraph "Backend Microservices"
        AUTH["Auth Service"]:::backend
        MAIL["Mail Service"]:::backend
        POCKET["PocketBase"]:::backend
        STOCK["Stock Service"]:::backend
    end

    %% Shared Packages Subgraph
    subgraph "Shared Packages"
        TYPES["Shared Types"]:::shared
        UTILS["Utility Packages"]:::shared
    end

    %% CI/CD deploys to Frontend Applications
    CICD -->|"deploys"| WEBAPP
    CICD -->|"deploys"| WEBSITE
    CICD -->|"deploys"| DOCS

    %% CI/CD deploys to Backend Microservices
    CICD -->|"deploys"| AUTH
    CICD -->|"deploys"| MAIL
    CICD -->|"deploys"| POCKET
    CICD -->|"deploys"| STOCK

    %% Frontend to Backend API calls (mainly from Webapp)
    WEBAPP -->|"HTTP_API"| AUTH
    WEBAPP -->|"HTTP_API"| MAIL
    WEBAPP -->|"HTTP_API"| POCKET
    WEBAPP -->|"HTTP_API"| STOCK

    %% Frontend Applications using Shared Packages
    WEBAPP -.->|"uses"| TYPES
    WEBAPP -.->|"uses"| UTILS

    %% Backend Microservices using Shared Packages
    AUTH -.->|"uses"| TYPES
    AUTH -.->|"uses"| UTILS

    MAIL -.->|"uses"| TYPES
    MAIL -.->|"uses"| UTILS

    POCKET -.->|"uses"| TYPES
    POCKET -.->|"uses"| UTILS

    STOCK -.->|"uses"| TYPES
    STOCK -.->|"uses"| UTILS

    %% Click Events
    click WEBAPP "https://github.com/budgetbuddyde/budgetbuddyde/tree/main/apps/webapp"
    click WEBSITE "https://github.com/budgetbuddyde/budgetbuddyde/tree/main/apps/website"
    click DOCS "https://github.com/budgetbuddyde/budgetbuddyde/tree/main/apps/documentation"
    click AUTH "https://github.com/budgetbuddyde/budgetbuddyde/tree/main/services/auth-service"
    click MAIL "https://github.com/budgetbuddyde/budgetbuddyde/tree/main/services/mail-service"
    click POCKET "https://github.com/budgetbuddyde/budgetbuddyde/tree/main/services/pocketbase"
    click STOCK "https://github.com/budgetbuddyde/budgetbuddyde/tree/main/services/stock-service"
    click TYPES "https://github.com/budgetbuddyde/budgetbuddyde/tree/main/packages/types"
    click UTILS "https://github.com/budgetbuddyde/budgetbuddyde/tree/main/packages/utils"
    click CICD "https://github.com/budgetbuddyde/budgetbuddyde/tree/main/ci"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef backend fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef shared fill:#D5F5E3,stroke:#1E8449,stroke-width:2px;
    classDef cicd fill:#F5B7B1,stroke:#943126,stroke-width:2px;
```
