# mathehluiz/nosso-bolso architecture

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

- Interactive diagram: https://gitdiagram.com/mathehluiz/nosso-bolso
- Repository: https://github.com/mathehluiz/nosso-bolso

## Overview

##### Project Type and Purpose
- This is a full-stack, multi-tenant financial tracking application (“Nosso bolso”) that allows users (individually or in shared groups) to manage bank accounts, transactions, categories, budgets, goals, and view reports.
- The “api” directory is a NestJS monolithic backend exposing REST endpoints, using Prisma for database access.
- The “www” directory is a Next.js frontend (with NextAuth), calling the backend via HTTP and presenting a dashboard, forms, and reports.

##### Top-Level Architecture Components
a. Frontend (Next.js “www”):
- Pages & Layout (public / protected)
- UI Components (dashboard cards, forms, charts)
- API Client & Services (http-client.ts + domain-specific service functions)
- Authentication (NextAuth routes + auth-provider)
b. Backend (NestJS “api”):
- API Gateway (NestJS Controllers / REST endpoints)
- Domain Modules:
- Organization & Identity (user signup/sign-in, invitation, roles)
- Bank Account (create/update accounts, default account)
- Transaction Category (CRUD categories)
- Transaction Management (CRUD transactions, mark paid)
- Goals (CRUD shared financial goals)
- Transaction Report (aggregate reports)
- Shared Modules:
- Persistence (PrismaService & repositories)
- Event Emitter (intra-module event bus)
- Config & Logger
- Database (PostgreSQL via Prisma ORM + Migrations)
c. Infrastructure
- Docker & docker-compose
- Environment configuration (.env files / config module)
- CI/Test (Jest unit/integration/e2e in “api/test”)

##### Relationships and Data Flows
1. User → Next.js UI (browser)
2. Next.js → NextAuth → External Identity Provider or JWT session store
3. Next.js UI calls backend REST endpoints (HTTP requests)
4. NestJS Controllers → Services (business logic) → Repositories (Prisma DB operations)
5. Business services emit domain events → Event Emitter Module → other handlers (e.g., cross-domain updates)
6. Services may publish read-model updates or generate reports on demand
7. Frontend polls or fetches updated data for real-time collaboration

##### Architectural Patterns & Design Principles
- Layered architecture in NestJS (Controller → Service → Repository)
- Domain-Driven Modularization: Each domain feature lives in its own NestJS module.
- Shared modules for cross-cutting concerns (logging, config, persistence, events).
- API-First design: Backend exposes REST, consumed by a clearly separated frontend.
- Event-Driven internals: Domain events for decoupling modules.
- Prisma Migrations for evolving schema.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Tier
    subgraph "Client Tier"
        direction TB
        Browser["Next.js Frontend"]:::frontend
        Auth["Authentication (NextAuth)"]:::auth
        Browser -->|"session/authenticate"| Auth
        Browser -->|"HTTP requests"| APIGateway
    end

    %% API Tier
    subgraph "API Tier" 
        direction TB
        subgraph "API Container"
            direction TB
            APIGateway["NestJS API Controllers"]:::backend
            subgraph "Domain Modules"
                direction TB
                OrgModule["Organization & Identity Module"]:::backend
                BankModule["Bank Account Module"]:::backend
                CategoryModule["Transaction Category Module"]:::backend
                TransactionModule["Transaction Management Module"]:::backend
                GoalModule["Goals Module"]:::backend
                ReportModule["Transaction Report Module"]:::backend
            end
            subgraph "Shared Modules"
                direction TB
                Persistence["Persistence (Prisma)"]:::backend
                EventBus["Event Emitter"]:::backend
                ConfigLogger["Config & Logger"]:::backend
            end
            %% Controller to Services
            APIGateway -->|calls| OrgModule
            APIGateway -->|calls| BankModule
            APIGateway -->|calls| CategoryModule
            APIGateway -->|calls| TransactionModule
            APIGateway -->|calls| GoalModule
            APIGateway -->|calls| ReportModule

            %% Services to Persistence
            OrgModule -->|uses| Persistence
            BankModule -->|uses| Persistence
            CategoryModule -->|uses| Persistence
            TransactionModule -->|uses| Persistence
            GoalModule -->|uses| Persistence
            ReportModule -->|uses| Persistence

            %% Event bus
            OrgModule -->|emits events| EventBus
            BankModule -->|emits events| EventBus
            TransactionModule -->|emits events| EventBus
            EventBus -->|handled by| OrgModule
            EventBus -->|handled by| ReportModule

            %% Config & Logger usage
            OrgModule -->|config/log| ConfigLogger
            BankModule -->|config/log| ConfigLogger
            CategoryModule -->|config/log| ConfigLogger
            TransactionModule -->|config/log| ConfigLogger
            GoalModule -->|config/log| ConfigLogger
            ReportModule -->|config/log| ConfigLogger
        end
    end

    %% Data Tier
    subgraph "Data Tier"
        direction TB
        Database["PostgreSQL (Prisma ORM)"]:::db
        Persistence -->|ORM queries| Database
        Database -->|migrations| Migrations["Prisma Migrations"]:::db
    end

    %% Infrastructure
    subgraph "Infrastructure"
        direction TB
        Docker["Docker & docker-compose"]:::infra
        Browser -.->|deployed in| Docker
        APIContainer["API Container"]-.->|deployed in| Docker
        DBContainer["DB Container"]-.->|deployed in| Docker
    end

    %% Click Events Frontend
    click Browser "https://github.com/mathehluiz/nosso-bolso/blob/main/www/src/app/page.tsx"
    click Auth "https://github.com/mathehluiz/nosso-bolso/blob/main/www/src/app/api/auth/[...nextauth]/route.ts"
    click PagesLayout "https://github.com/mathehluiz/nosso-bolso/blob/main/www/src/app/layout.tsx"
    click UIComponents "https://github.com/mathehluiz/nosso-bolso/tree/main/www/src/components/ui"
    click HTTPClient "https://github.com/mathehluiz/nosso-bolso/blob/main/www/src/lib/http-client.ts"
    click Services "https://github.com/mathehluiz/nosso-bolso/tree/main/www/src/services"

    %% Click Events Backend
    click APIGateway "https://github.com/mathehluiz/nosso-bolso/blob/main/api/src/organization/identity/http/auth.controller.ts"
    click ReportModule "https://github.com/mathehluiz/nosso-bolso/blob/main/api/src/transaction/transaction-report/http/controlller/transaction-report.controller.ts"
    click OrgModule "https://github.com/mathehluiz/nosso-bolso/blob/main/api/src/organization/identity/identity.module.ts"
    click BankModule "https://github.com/mathehluiz/nosso-bolso/blob/main/api/src/bank-account/bank-account.module.ts"
    click CategoryModule "https://github.com/mathehluiz/nosso-bolso/blob/main/api/src/transaction/category-management/category-management.module.ts"
    click TransactionModule "https://github.com/mathehluiz/nosso-bolso/blob/main/api/src/transaction/transaction-management/transaction-management.module.ts"
    click GoalModule "https://github.com/mathehluiz/nosso-bolso/blob/main/api/src/bank-account/goal/goal.module.ts"
    click Persistence "https://github.com/mathehluiz/nosso-bolso/blob/main/api/src/shared/module/persistence/prisma/persistence.module.ts"
    click EventBus "https://github.com/mathehluiz/nosso-bolso/blob/main/api/src/shared/module/event/event-emitter.module.ts"
    click ConfigLogger "https://github.com/mathehluiz/nosso-bolso/blob/main/api/src/shared/module/config/config.module.ts"
    click Migrations "https://github.com/mathehluiz/nosso-bolso/tree/main/api/database/prisma/migrations/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,stroke-width:1px;
    classDef auth fill:#E8F4FF,stroke:#1E70BF,stroke-width:1px;
    classDef backend fill:#E0FFDE,stroke:#028A0F,stroke-width:1px;
    classDef db fill:#F0F0F0,stroke:#666666,stroke-width:1px;
    classDef infra fill:#F5F5F5,stroke:#999999,stroke-width:1px;
```
