# dreeilima/fincontrol-web architecture

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

- Interactive diagram: https://gitdiagram.com/dreeilima/fincontrol-web
- Repository: https://github.com/dreeilima/fincontrol-web

## Overview

##### Main Components
- Frontend Client:
- The “app” directory is subdivided into route groups (such as (auth), (dashboard), (docs), (marketing), (protected), and checkout), indicating a rich client-side interface composed of both public-facing pages (marketing, blog, docs) and protected areas (dashboard, admin, onboarding).
- UI components are extensively used (located in the “components” folder) with dedicated subdirectories for admin, dashboard, charts, forms, UI primitives, etc.
- Styling is handled via Tailwind CSS and Shadcn/ui components, and animations (with Framer Motion) are integrated as needed.

- Backend/API Layer:
- The “app/api” directory contains a comprehensive set of endpoints that serve different purposes: handling authentication (using Auth.js via NextAuth routes), processing payments (checkout, subscription, Stripe operations), managing users, categories, transactions, reports, and administrative tasks.
- Server-side logic is implemented in several TypeScript files across the “actions” folder and in other specific API endpoints.

- Database and ORM:
- Prisma is used as the ORM (see the “prisma” folder with schema.prisma and migrations) to communicate with Neon (serverless Postgres). All data access, transactions, and migrations are managed via Prisma.

- External Services & Integrations:
- Stripe is integrated into several API endpoints and library functions (“lib/stripe.ts” and related routes) for payment processing.
- Auth.js (via NextAuth routes) secures user authentication and sessions.
- Email functionalities are provided using Resend/React Email, with email templates found in the “emails” directory.
- Other integrations include analytics (via Vercel Analytics) and static asset delivery (through the “public” folder).

- Utility & Shared Libraries:
- There is a rich set of shared hooks (in “hooks”), libraries (under “lib”), and context providers (“contexts”) that support cross-cutting concerns like authentication, state management, and UI interactions.
- Configuration files under “config” and “env” plus TypeScript types in “types” ensure that the overall system is well organized and type-safe.

##### Relationships and Interactions
- The Frontend interacts with the Backend through API calls defined in the “app/api” routes. These endpoints trigger operations such as fetching financial data, processing transactions, and handling user sessions.
- API endpoints rely on the ORM (Prisma) to perform database CRUD operations. The “prisma” folder illustrates the migration and schema setup which connects to the Neon database.
- Many of the API functions serve as bridges between user interactions (captured in the UI) and external services like Stripe for billing or Resend for sending emails.
- Middleware in the “middleware.ts” file manages pre-request processing (likely route protection or authentication checks).

##### Architectural Patterns and Design Principles
- Separation of Concerns: The project is neatly segmented — frontend components (UI, pages, layouts) are separated into route groups, while API logic resides in its own namespace. This improves maintainability and clarity.
- Modular Design: With dedicated folders for actions, components, contexts, hooks, and utilities, each subsystem is encapsulated, making it easier to extend or modify functionality.
- API-driven Interactions: The system predominantly uses server-side API functions to manage data and business logic.
- Security & Authentication: Uses Auth.js (wrapped in NextAuth endpoints) for secure, extensible user authentication.
- Code Quality & Typing: The use of TypeScript, ESLint, and Prettier ensures that the project maintains high standards of code quality and consistency.

##### Elements
- Third-party integrations, specifying the role of each (e.g., “Stripe: Payment Processing”).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Subgraph
    subgraph "Frontend (Next.js Client)"
        A["App Directory (Next.js App)"]:::frontend
        A1["Public Pages ((marketing),(docs),blog)"]:::frontend
        A2["User Auth Areas ((auth),(protected),dashboard/admin)"]:::frontend
        A3["Checkout & Payment Pages"]:::frontend
        A4["UI Components"]:::frontend
        A5["Styling & Shadcn/ui"]:::frontend
    end

    %% Backend API Subgraph
    subgraph "Backend API"
        B["API Endpoints (app/api)"]:::backend
        B1["Server-side Actions (actions)"]:::backend
        B2["Middleware (middleware.ts)"]:::backend
    end

    %% Database Subgraph
    subgraph "Database Layer"
        C["Neon Postgres via Prisma"]:::database
    end

    %% External Services Subgraph
    subgraph "External Services & Integrations"
        D["Stripe (Payment Processing)"]:::external
        E["Auth Service (Auth.js/NextAuth)"]:::external
        F["Email Service (Resend/React Email)"]:::external
    end

    %% Supporting Libraries Subgraph
    subgraph "Supporting Libraries"
        G["Shared Utilities & Hooks (lib,hooks,contexts)"]:::utility
    end

    %% Connections and Flows
    A -->|"APIcalls"| B
    B1 --> B
    B2 --> B
    B -->|"DBCRUD"| C
    B -->|"StripeCalls"| D
    B -->|"AuthCalls"| E
    B -->|"EmailCalls"| F
    B -->|"Uses"| G
    A2 -->|"AuthFlow"| E
    A3 -->|"InitiatesPayment"| D

    %% Click Events for Component Mappings
    click A "https://github.com/dreeilima/fincontrol-web/tree/main/app"
    click A4 "https://github.com/dreeilima/fincontrol-web/tree/main/components"
    click A5 "https://github.com/dreeilima/fincontrol-web/tree/main/styles"
    click A5 "https://github.com/dreeilima/fincontrol-web/blob/main/tailwind.config.ts"
    click B "https://github.com/dreeilima/fincontrol-web/tree/main/app/api"
    click B1 "https://github.com/dreeilima/fincontrol-web/tree/main/actions"
    click C "https://github.com/dreeilima/fincontrol-web/tree/main/prisma"
    click D "https://github.com/dreeilima/fincontrol-web/blob/main/lib/stripe.ts"
    click D "https://github.com/dreeilima/fincontrol-web/blob/main/components/providers/stripe-provider.tsx"
    click E "https://github.com/dreeilima/fincontrol-web/blob/main/app/api/auth/[...nextauth]"
    click E "https://github.com/dreeilima/fincontrol-web/blob/main/auth.ts"
    click F "https://github.com/dreeilima/fincontrol-web/tree/main/emails"
    click F "https://github.com/dreeilima/fincontrol-web/blob/main/lib/email.ts"
    click G "https://github.com/dreeilima/fincontrol-web/tree/main/lib"
    click G "https://github.com/dreeilima/fincontrol-web/tree/main/hooks"
    click G "https://github.com/dreeilima/fincontrol-web/tree/main/contexts"
    click B2 "https://github.com/dreeilima/fincontrol-web/blob/main/middleware.ts"

    %% Styles and Classes
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef database fill:#fff3cd,stroke:#856404,stroke-width:2px,stroke-dasharray: 5 5;
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef utility fill:#e2e3e5,stroke:#41464b,stroke-width:2px;
    
    %% Ensure vertical layout
    style A fill:#cce5ff,stroke:#004085
    style B fill:#d4edda,stroke:#155724
    style C fill:#fff3cd,stroke:#856404
    style D fill:#f8d7da,stroke:#721c24
    style E fill:#f8d7da,stroke:#721c24
    style F fill:#f8d7da,stroke:#721c24
    style G fill:#e2e3e5,stroke:#41464b
```
