# thibault-hen/la-pince architecture

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

- Interactive diagram: https://gitdiagram.com/thibault-hen/la-pince
- Repository: https://github.com/thibault-hen/la-pince

## Overview

##### Project Type and Purpose
- This is a full-stack personal finance application (“La Pince”) comprised of a Node.js/TypeScript backend and a React/TypeScript frontend. The backend exposes REST and WebSocket endpoints for user authentication, budget tracking, expenses, incomes, notifications, and currency exchange. The frontend uses Vite, React, and a custom component library to render pages, forms, charts, and modals for managing personal finances.

##### File Structure Analysis
- Top-level folders:
- backend – Node.js/Express (app.ts, router.ts), Prisma ORM with migrations, Redis integration, mailing service, middleware (auth, logger), controllers, services, WebSockets for real-time notifications, tests (vitest).
- frontend – Vite/React app in src, organized by assets, components (UI primitives, domain modules: auth, budget, expense, etc.), hooks, services to call backend APIs, stores (state management), layouts, pages, schemas, i18n, tests.
- .github/workflows/ci-cd.yaml for automated CI/CD.
- Dockerfiles and docker-compose setup to bring up backend, PostgreSQL, Redis.

##### README Insights
- Confirms Docker Compose brings up backend + PostgreSQL + Redis.
- Frontend runs independently in dev mode (npm run dev).

a. Main Components
- Frontend SPA (React/Vite)
- Backend API Server (Node.js/Express)
- PostgreSQL Database (Prisma ORM)
- Redis Cache/Session Store
- Email Service (mailer service via SMTP or third-party)
- CI/CD pipeline (GitHub Actions)
b. Relationships and Interactions
- Frontend ↔ Backend over HTTPS (RESTful endpoints)
- Backend ↔ PostgreSQL for CRUD operations (Prisma)
- Backend ↔ Redis for rate-limiting, sessions, notifications
- Backend WebSocket server → Frontend (real-time notifications)
- Backend → Email Service for password resets and notifications
- GitHub Actions → Docker Hub/Vercel (deployment)
c. Architectural Patterns and Principles
- Layered architecture on the backend:
- HTTP controllers → service layer → ORM layer → external systems (DB, Redis, mailer)
- REST API design with JSON, plus WebSocket for push notifications
- MVC-style separation: controllers, services, middlewares, validators
- Frontend component-driven UI with state management via custom hooks and stores
- I18n for multi-language support
d. Key Technologies
- Node.js, Express, TypeScript, Prisma, PostgreSQL, Redis, Vitest
- Vite, React, TypeScript, Zustand (or similar) stores, i18next, Tailwind or custom CSS, Sonner for toasts
- Docker, Docker Compose, GitHub Actions, Vercel

##### Detailed Capture of Architectural Elements
- Middleware chain on the backend (logger, auth, rate limiter).
- WebSocket channel topics and how notifiableUsers are tracked.
- Which components are covered by Vitest tests for design completeness.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend (React/Vite)" 
        direction TB
        FL_SPA["SPA Entry"]:::frontend
        FL_SPA --> FL_RTR
        FL_RTR["Router"]:::frontend
        FL_RTR --> FL_PAGES
        FL_PAGES["Pages"]:::frontend
        FL_PAGES --> FL_COMPONENTS
        FL_COMPONENTS["Components"]:::frontend
        FL_COMPONENTS --> FL_SERVICES
        FL_SERVICES["API Services"]:::frontend
        FL_SERVICES --> FL_STORES
        FL_STORES["State Stores"]:::frontend
        FL_STORES --> FL_SCHEMAS
        FL_SCHEMAS["Schemas & Types"]:::frontend
        FL_SCHEMAS --> FL_CONFIG
        FL_CONFIG["Config"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (Node.js/Express)" 
        direction TB
        %% API Gateway
        subgraph "API Layer"
            direction TB
            BE_APP["app.ts / index.ts"]:::backend
            BE_APP --> BE_ROUTER
            BE_ROUTER["router.ts"]:::backend
            BE_ROUTER --> BE_MW
            BE_MW["Middlewares"]:::backend
            BE_MW --> BE_CTRL
            BE_CTRL["Controllers"]:::backend
        end

        %% Business Logic
        subgraph "Service Layer"
            direction TB
            BE_SVC["Services"]:::backend
            BE_SVC --> BE_WS
            BE_WS["WebSockets"]:::backend
            BE_WS --> BE_MAIL
            BE_MAIL["Mailer Service"]:::backend
        end

        %% Data Access
        subgraph "Data Access Layer"
            direction TB
            BE_DBCL["Prisma Client"]:::database
            BE_DBCL --> BE_SEED
            BE_SEED["Seeding"]:::backend
        end

        %% Cache and Sessions
        BE_REDIS["Redis Cache/Session"]:::cache

        %% External DB and Cache
        BE_DBCL -->|"Prisma queries"| POSTGRES
        BE_REDIS -->|"PUB/SUB & sessions"| POSTGRES
    end

    %% External Systems
    POSTGRES[(PostgreSQL Database)]:::database
    REDIS[(Redis)]:::cache
    SMTP((SMTP Service)):::external
    CI_CD[[CI/CD Pipeline]]:::external

    %% Interactions
    FL_SERVICES -->|"HTTPS REST"| BE_ROUTER
    BE_SVC -->|"Background jobs"| BE_REDIS
    BE_SVC -->|"Send emails"| SMTP
    BE_WS -->|"WebSocket"| FL_SPA
    CI_CD -->|"Build/Test/Deploy"| BE_APP
    CI_CD -->|"Build/Test/Deploy"| FL_SPA

    %% Click Events
    click FL_SPA "https://github.com/thibault-hen/la-pince/tree/main/frontend/src"
    click FL_RTR "https://github.com/thibault-hen/la-pince/blob/main/frontend/src/router.tsx"
    click FL_SPA "https://github.com/thibault-hen/la-pince/blob/main/frontend/src/main.tsx"
    click FL_COMPONENTS "https://github.com/thibault-hen/la-pince/tree/main/frontend/src/components"
    click FL_PAGES "https://github.com/thibault-hen/la-pince/tree/main/frontend/src/pages"
    click FL_SERVICES "https://github.com/thibault-hen/la-pince/tree/main/frontend/src/services"
    click FL_STORES "https://github.com/thibault-hen/la-pince/tree/main/frontend/src/stores"
    click FL_SCHEMAS "https://github.com/thibault-hen/la-pince/tree/main/frontend/src/schemas"
    click FL_CONFIG "https://github.com/thibault-hen/la-pince/blob/main/frontend/vite.config.ts"
    click BE_APP "https://github.com/thibault-hen/la-pince/blob/main/backend/src/app.ts"
    click BE_APP "https://github.com/thibault-hen/la-pince/blob/main/backend/src/index.ts"
    click BE_ROUTER "https://github.com/thibault-hen/la-pince/blob/main/backend/src/router.ts"
    click BE_MW "https://github.com/thibault-hen/la-pince/tree/main/backend/src/middlewares"
    click BE_CTRL "https://github.com/thibault-hen/la-pince/tree/main/backend/src/controllers"
    click BE_SVC "https://github.com/thibault-hen/la-pince/tree/main/backend/src/services"
    click BE_WS "https://github.com/thibault-hen/la-pince/blob/main/backend/src/websockets/notifiableUsers.ts"
    click BE_MAIL "https://github.com/thibault-hen/la-pince/blob/main/backend/src/services/mailer.ts"
    click BE_DBCL "https://github.com/thibault-hen/la-pince/blob/main/backend/src/db/client.ts"
    click BE_SEED "https://github.com/thibault-hen/la-pince/blob/main/backend/src/db/seeding.ts"
    click BE_REDIS "https://github.com/thibault-hen/la-pince/blob/main/backend/src/utils/redis.ts"
    click POSTGRES "https://github.com/thibault-hen/la-pince/blob/main/backend/prisma/schema.prisma"
    click CI_CD "https://github.com/thibault-hen/la-pince/blob/main/.github/workflows/ci-cd.yaml"

    %% Styles
    classDef frontend fill:#e3f2fd,stroke:#1e88e5,color:#0d47a1
    classDef backend fill:#f3e5f5,stroke:#8e24aa,color:#4a148c
    classDef database fill:#fff9c4,stroke:#fbc02d,color:#bf360c
    classDef cache fill:#e0f7fa,stroke:#00acc1,color:#006064
    classDef external fill:#ffecb3,stroke:#ffa000,color:#ff6f00
```
