# rosanarezende/balanceamento-de-investimentos architecture

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

- Interactive diagram: https://gitdiagram.com/rosanarezende/balanceamento-de-investimentos
- Repository: https://github.com/rosanarezende/balanceamento-de-investimentos

## Overview

##### Project Type and Purpose
- EquilibreInvest is a full-stack, single-page web application built with Next.js (App Router) and React.
- It assists users in balancing stock portfolios, offering CRUD on assets, balance simulations, history tracking, dashboards, and watchlists.
- It integrates Firebase for authentication and data storage, external market-data APIs, and AI services for recommendations.

##### File Structure
- Top-level config & tooling: ESLint, Prettier, Jest, Tailwind, GitHub Actions, Vercel config.
- src/app – Next.js routing structure: pages (login, dashboard, calculadora-balanceamento, historico, carteira, editar-ativos), and API routes under src/app/api (stock-price, ai-recommendation).
- src/components – UI primitives (components/ui), domain components (dashboard, carteira, watchlist, calculators, modals).
- src/core – application schemas (Zod), global state (AuthContext, PortfolioContext, ThemeContext), common types and utilities.
- src/services – external integrations: Firebase config & Firestore, market-data API clients, AI text-generation.
- src/hooks, src/utils, src/styles – cross-cutting concerns and styling.
- tests – unit and integration tests for key features (auth, calculator, performance).

##### README Insights
- Frontend layer (App Shell, ThemeProvider, UI Library, Pages)
- Contexts for state management
- Next.js API routes as backend
- Firebase as the data layer
- External services (Alpha Vantage/Yahoo, AI text)
- CI/CD via GitHub Actions & Vercel

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        User("User"):::external
        Browser("Browser"):::frontend
        AppShell["App Shell (app-shell-enhanced)"]:::frontend
        UIComponents["UI Components Library"]:::frontend
        LoginPage["Login Page"]:::frontend
        DashboardPage["Dashboard Pages"]:::frontend
        PortfolioPage["Portfolio Pages"]:::frontend
        CalculatorPage["Calculator Pages"]:::frontend
        HistoryPage["History Pages"]:::frontend
        EditAssetsPage["Asset Editing Pages"]:::frontend
        ThemeToggle["Theme Toggle"]:::frontend
    end

    %% State Management Layer
    subgraph "State Management"
        direction TB
        AuthContext["AuthContext"]:::state
        PortfolioContext["PortfolioContext"]:::state
        ThemeContext["ThemeContext"]:::state
        ErrorHandling["ErrorHandling State"]:::state
    end

    %% API Layer
    subgraph "API Layer (Next.js Routes)"
        direction TB
        StockPriceAPI["/api/stock-price"]:::api
        AIRecommendationAPI["/api/ai-recommendation"]:::api
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        FirebaseAuth["Firebase Auth"]:::data
        Firestore["Firestore"]:::data
    end

    %% External Services
    subgraph "External Services"
        direction TB
        MarketDataService["Market Data API"]:::external
        AIService["AI Recommendation Service"]:::external
    end

    %% Infrastructure
    subgraph "Infrastructure & CI/CD"
        direction TB
        GitHubActions["GitHub Actions CI"]:::infra
        Vercel["Vercel Deployment"]:::infra
    end

    %% Connections
    User -->|"uses"| Browser
    Browser -->|renders| AppShell
    AppShell -->|provides layout| UIComponents
    AppShell -->|wraps| ThemeToggle
    AppShell --> LoginPage
    AppShell --> DashboardPage
    AppShell --> PortfolioPage
    AppShell --> CalculatorPage
    AppShell --> HistoryPage
    AppShell --> EditAssetsPage

    %% State connections
    LoginPage -->|reads/writes| AuthContext
    DashboardPage -->|uses| PortfolioContext
    PortfolioPage -->|uses| PortfolioContext
    CalculatorPage -->|reads/writes| PortfolioContext
    AllPages -->|toggles theme| ThemeContext
    AllPages -->|handles errors| ErrorHandling

    click AllPages "https://github.com/rosanarezende/balanceamento-de-investimentos/tree/main/src/app"
    click UIComponents "https://github.com/rosanarezende/balanceamento-de-investimentos/tree/main/src/components/ui"
    click AppShell "https://github.com/rosanarezende/balanceamento-de-investimentos/blob/main/src/components/layout/app-shell-enhanced.tsx"
    click ThemeToggle "https://github.com/rosanarezende/balanceamento-de-investimentos/blob/main/src/components/theme-toggle.tsx"
    click ThemeContext "https://github.com/rosanarezende/balanceamento-de-investimentos/blob/main/src/core/state/theme-context.tsx"
    click AuthContext "https://github.com/rosanarezende/balanceamento-de-investimentos/blob/main/src/core/state/auth-context.tsx"
    click PortfolioContext "https://github.com/rosanarezende/balanceamento-de-investimentos/blob/main/src/core/state/portfolio-context.tsx"
    click ErrorHandling "https://github.com/rosanarezende/balanceamento-de-investimentos/blob/main/src/core/state/error-handling.tsx"
    click LoginPage "https://github.com/rosanarezende/balanceamento-de-investimentos/blob/main/src/app/login/page.tsx"
    click DashboardPage "https://github.com/rosanarezende/balanceamento-de-investimentos/tree/main/src/components/dashboard"
    click PortfolioPage "https://github.com/rosanarezende/balanceamento-de-investimentos/tree/main/src/app/carteira"
    click CalculatorPage "https://github.com/rosanarezende/balanceamento-de-investimentos/tree/main/src/app/calculadora-balanceamento"
    click HistoryPage "https://github.com/rosanarezende/balanceamento-de-investimentos/tree/main/src/app/historico"
    click EditAssetsPage "https://github.com/rosanarezende/balanceamento-de-investimentos/tree/main/src/app/editar-ativos"

    %% API calls
    DashboardPage -->|fetches price| StockPriceAPI
    PortfolioPage -->|fetches price| StockPriceAPI
    CalculatorPage -->|requests recommendation| AIRecommendationAPI

    StockPriceAPI -->|proxies to| MarketDataService
    AIRecommendationAPI -->|proxies to| AIService

    click StockPriceAPI "https://github.com/rosanarezende/balanceamento-de-investimentos/blob/main/src/app/api/stock-price/route.ts"
    click AIRecommendationAPI "https://github.com/rosanarezende/balanceamento-de-investimentos/blob/main/src/app/api/ai-recommendation/route.ts"
    click MarketDataService "https://github.com/rosanarezende/balanceamento-de-investimentos/blob/main/src/services/api/stock-price.ts"
    click AIService "https://github.com/rosanarezende/balanceamento-de-investimentos/blob/main/src/services/ai/textGeneration.ts"

    %% Data layer interactions
    AuthContext -->|auth operations| FirebaseAuth
    PortfolioContext -->|read/write| Firestore

    click FirebaseAuth "https://github.com/rosanarezende/balanceamento-de-investimentos/blob/main/src/services/firebase/config.ts"
    click Firestore "https://github.com/rosanarezende/balanceamento-de-investimentos/blob/main/src/services/firebase/firestore.ts"

    %% Infra
    GitHubActions -->|deploy trigger| Vercel
    Vercel -->|deploys| AppShell

    click GitHubActions "https://github.com/rosanarezende/balanceamento-de-investimentos/blob/main/.github/workflows/ci.yml"
    click Vercel "https://github.com/rosanarezende/balanceamento-de-investimentos/blob/main/next.config.mjs"

    %% Styles and utilities
    subgraph "Cross-cutting Concerns"
        direction TB
        ZodSchemas["Zod Schemas"]:::state
        TypesUtils["Common Types & Utils"]:::state
        Hooks["Custom Hooks"]:::state
        ClientCache["Client Cache"]:::state
        GlobalStyles["Global Styles"]:::frontend
    end

    click ZodSchemas "https://github.com/rosanarezende/balanceamento-de-investimentos/tree/main/src/core/schemas"
    click TypesUtils "https://github.com/rosanarezende/balanceamento-de-investimentos/tree/main/src/core/types"
    click Hooks "https://github.com/rosanarezende/balanceamento-de-investimentos/blob/main/src/hooks/use-mobile.ts"
    click Hooks "https://github.com/rosanarezende/balanceamento-de-investimentos/blob/main/src/hooks/use-toast.ts"
    click ClientCache "https://github.com/rosanarezende/balanceamento-de-investimentos/blob/main/src/utils/client/cache.ts"
    click GlobalStyles "https://github.com/rosanarezende/balanceamento-de-investimentos/blob/main/src/styles/globals.css"
    click GlobalStyles "https://github.com/rosanarezende/balanceamento-de-investimentos/blob/main/tailwind.config.ts"

    %% Classes
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef state fill:#E6F4EA,stroke:#22863A,color:#22863A
    classDef api fill:#E3FCEF,stroke:#34D058,color:#1B1F23
    classDef data fill:#FFF5B1,stroke:#D29922,color:#6A5800
    classDef external fill:#F0F0F0,stroke:#959DA5,color:#24292E
    classDef infra fill:#FBEFEF,stroke:#D73A49,color:#86181D
```
