# ottoengel/finally architecture

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

- Interactive diagram: https://gitdiagram.com/ottoengel/finally
- Repository: https://github.com/ottoengel/finally

## Overview

##### Project type and purpose
- This is a full-stack web application built with Next.js (App Router), TypeScript, Tailwind CSS, and Prisma.
- The domain appears to be a personal-finance or subscription-based transaction tracker with features like AI-driven reporting, Stripe-powered payments, and user dashboards.

##### High-level architecture components
a. Client (Browser)
- React components under `app/(…)` that render pages (Home, Dashboard, Login, Subscription, Transactions)
- Client-side interactivity (buttons, dialogs, forms, charts) via the `_components/ui` library
b. Next.js Server
- App Router handles routing and SSR/SSG for pages (`app/page.tsx`, `app/dashboard/page.tsx`, etc.)
- Server Actions (`app/_actions`, `app/dashboard/_actions`, etc.) for form submissions and data mutations
- API Routes (`app/api/webhooks/stripe/route.ts`) to receive Stripe webhooks
c. Database
- Prisma ORM layer (`app/_lib/prisma.ts`) connecting to a SQL database defined in `prisma/schema.prisma`
- Migrations under `prisma/migrations/`
d. External Services
- Stripe API – checkout sessions, webhook events
- (Likely) OpenAI or other AI service for generating dashboard reports in `generate-ai-report`
e. Infrastructure / Deployment
- Vercel serverless functions (Next.js app deployment)
- CI pre-commit hooks (Husky) and linting/prettier configurations for code quality

##### Relationships and data flows
1. User’s browser requests a page → Next.js Server
2. Server renders React components + static assets (`public/`, `globals.css`) → Browser
3. User interacts (e.g., “Add Transaction” button) → triggers a Server Action
- Server Action calls Prisma to read/write the database
- Server returns updated props to the client (revalidation or streamed SSR)
4. Subscription flow
- Client invokes `create-stripe-checkout` Server Action → calls Stripe API → redirects user to Stripe hosted page
- Stripe webhook hits `app/api/webhooks/stripe/route.ts` → updates subscription status in database via Prisma
5. AI Reporting
- Dashboard “Generate AI Report” button → Server Action calls an AI service → writes report results back to DB or directly returns to client

##### Architectural patterns and design principles
- App-Router MVC-style separation:
- **View**: React components in `app/(…)`
- **Controller**: Server Actions & API Routes handle business logic
- **Model**: Prisma ORM + database schema
- Serverless micro-endpoints: each Server Action and API Route is its own function
- Shared UI library under `_components/ui` promotes design consistency and reusability
- Environment-driven configuration: Stripe keys, database URLs managed outside version control

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Side
    subgraph "Client (Browser)" 
        direction TB
        HomePage["Home Page"]:::frontend
        DashboardPage["Dashboard Page"]:::frontend
        LoginPage["Login Page"]:::frontend
        SubscriptionPage["Subscription Page"]:::frontend
        TransactionsPage["Transactions Page"]:::frontend
        SharedUI["Shared UI Library"]:::frontend
        Navigation["Navigation & Common Components"]:::frontend
    end

    %% Server Side
    subgraph "Next.js Server" 
        direction TB
        AppRouter["App Router"]:::backend
        Layout["Layout & Globals.css"]:::backend
        subgraph "Server Actions" 
            direction TB
            UpsertTxn["Upsert Transaction"]:::backend
            GenerateReport["Generate AI Report"]:::backend
            CreateCheckout["Create Stripe Checkout"]:::backend
            DeleteTxn["Delete Transaction"]:::backend
        end
        APIRoute["Stripe Webhook API Route"]:::backend
        DataFetchers["Data Fetchers"]:::backend
        PrismaClient["Prisma Client"]:::backend
    end

    %% Database
    Database[(Database)]:::db

    %% External Services
    Stripe["Stripe API"]:::external
    AIService["AI Service"]:::external

    %% Data Flows
    HomePage -->|"HTTP GET /"| AppRouter
    DashboardPage -->|"HTTP GET /dashboard"| AppRouter
    LoginPage -->|"HTTP GET /login"| AppRouter
    SubscriptionPage -->|"HTTP GET /subscription"| AppRouter
    TransactionsPage -->|"HTTP GET /transactions"| AppRouter

    AppRouter -->|"Render React Components"| HomePage
    AppRouter --> Layout
    Layout --> Navigation
    Layout --> SharedUI

    HomePage -->|"uses UI components"| SharedUI
    DashboardPage --> SharedUI
    SubscriptionPage --> SharedUI
    TransactionsPage --> SharedUI
    Navigation --> SharedUI

    HomePage --> UpsertTxn
    TransactionsPage --> DeleteTxn
    DashboardPage --> GenerateReport
    SubscriptionPage --> CreateCheckout

    UpsertTxn -->|"calls Prisma"| PrismaClient
    DeleteTxn --> PrismaClient
    GenerateReport --> AIService
    GenerateReport --> PrismaClient
    CreateCheckout --> Stripe
    Stripe -->|Redirect URL| SubscriptionPage

    Stripe -->|Webhook event| APIRoute
    APIRoute --> PrismaClient
    DataFetchers --> PrismaClient
    PrismaClient --> Database

    %% Click Events
    click HomePage "https://github.com/ottoengel/finally/blob/main/app/(home)/page.tsx"
    click DashboardPage "https://github.com/ottoengel/finally/blob/main/app/dashboard/page.tsx"
    click LoginPage "https://github.com/ottoengel/finally/blob/main/app/login/page.tsx"
    click SubscriptionPage "https://github.com/ottoengel/finally/blob/main/app/subscription/page.tsx"
    click TransactionsPage "https://github.com/ottoengel/finally/blob/main/app/transactions/page.tsx"
    click SharedUI "https://github.com/ottoengel/finally/tree/main/app/_components/ui/"
    click Navigation "https://github.com/ottoengel/finally/tree/main/app/_components/"
    click UpsertTxn "https://github.com/ottoengel/finally/blob/main/app/_actions/upsert-transaction/index.ts"
    click GenerateReport "https://github.com/ottoengel/finally/blob/main/app/dashboard/_actions/generate-ai-report/index.ts"
    click CreateCheckout "https://github.com/ottoengel/finally/blob/main/app/subscription/_actions/create-stripe-checkout/index.ts"
    click DeleteTxn "https://github.com/ottoengel/finally/blob/main/app/transactions/_actions/delete-transaction/index.ts"
    click APIRoute "https://github.com/ottoengel/finally/blob/main/app/api/webhooks/stripe/route.ts"
    click DataFetchers "https://github.com/ottoengel/finally/blob/main/app/_data/get-dashboard/index.ts"
    click PrismaClient "https://github.com/ottoengel/finally/blob/main/app/_lib/prisma.ts"

    %% Styles
    classDef frontend fill:#E0F2FE,stroke:#0284C7,color:#0369A1
    classDef backend fill:#D1FAE5,stroke:#10B981,color:#065F46
    classDef db fill:#F3F4F6,stroke:#6B7280,color:#374151
    classDef external fill:#FFEDD5,stroke:#F97316,color:#C2410C
```
