# faizm10/spendsmart architecture

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

- Interactive diagram: https://gitdiagram.com/faizm10/spendsmart
- Repository: https://github.com/faizm10/spendsmart

## Overview

##### Project Type and Purpose
- This is a full-stack financial tracking web application (“SpendSmart”) built with Next.js on the front end and Supabase providing the backend services (authentication, database, storage, SMTP).
- Users can sign up/sign in, reset passwords, add transactions, view charts, and manage their account via an interactive dashboard.

##### File Structure
- Top level “frontend” directory contains a Next.js 13+ “app” directory (React Server Components + Client Components).
- Key subdirectories:
- app/(auth-pages) – authentication flows (sign-in/up, forgot/reset-password)
- app/dashboard – protected routes (transactions, charts, account settings)
- components – reusable UI components, grouped by category (charts, forms, kokonutui, magicui, shadcn-based UI)
- hooks – custom React hooks (use-toast, use-mobile)
- lib – shared data utilities
- utils/supabase – Supabase client, middleware, server helpers
- Config files: next.config.js, tailwind.config.ts, tsconfig.json, package.json

##### README for Additional Insights
- Confirms frontend is Next.js + React + TailwindCSS.
- Supabase is used for Auth, database, and hosting functions.
- No separate custom backend code; backend is entirely Supabase-hosted.

##### Main Components and Their Interactions
a. Client Browser (User Agent)
- Sends HTTP(S) requests to Next.js server (SSR/SSG) and directly to Supabase via client SDK.
b. Next.js Frontend
- Routing and rendering of pages (React Server Components + Client Components).
- Server-side code (getServerSideProps or API routes) calls Supabase Admin client for secure operations.
- Client-side code (React hooks, use-supabase client) interacts with Supabase Auth and Database.
c. Supabase Services
- Auth: handles sign-in/sign-up, JWT issuance, password resets (SMTP).
- Postgres Database: stores user profiles, transactions, metadata.
- Storage (optional): for file uploads (not explicitly shown but common in Supabase apps).
- Edge Functions or serverless (if used).
d. External SMTP Provider
- Triggered by Supabase Auth to send reset/password emails.

##### Architectural Patterns & Design Principles
- Jamstack / Serverless-first: UI delivered by Next.js, data via API (Supabase).
- Component-driven design: small, focused UI components (charts, forms, UI primitives).
- Separation of concerns: authentication flows, dashboard flows, and shared utilities separated into distinct folders.
- React hooks for state & side-effect management.
- Theme and style management via Tailwind & custom provider (providers.tsx).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Browser["Client Browser"]:::frontend

    %% Next.js Application
    subgraph "Next.js Application"
        LayoutRoot["Root Layout\nlayout.tsx"]:::frontend
        EntryPage["Root Page\npage.tsx"]:::frontend

        Providers["Global Providers & Styling\n(providers.tsx, globals.css)"]:::frontend

        subgraph "Authentication Pages"
            SignIn["Sign-In Page"]:::frontend
            SignUp["Sign-Up Page"]:::frontend
            Forgot["Forgot Password Page"]:::frontend
        end

        AuthCallback["Authentication Callback Route\nroute.ts"]:::frontend

        subgraph "Dashboard Pages"
            DashboardHome["Dashboard Home Page"]:::frontend
            TransactionsPage["Transactions Page"]:::frontend
            ResetPwdPage["Reset Password Page"]:::frontend
        end

        Actions["Server Actions & API Helpers\nactions.ts"]:::frontend

        subgraph "Route Protection Middleware"
            Mil1["middleware.ts"]:::frontend
            Mil2["utils/supabase/middleware.ts"]:::frontend
        end

        subgraph "Supabase SDK Utilities"
            ClientSDK["Supabase Client (Browser SDK)\nclient.ts"]:::frontend
            ServerSDK["Supabase Server Helpers\nserver.ts"]:::frontend
            EnvCheck["Supabase Env Validator\ncheck-env-vars.ts"]:::frontend
        end

        subgraph "Hooks & Utilities"
            UseToast["use-toast Hook\nuse-toast.ts"]:::frontend
            UseMobile["use-mobile Hook\nuse-mobile.tsx"]:::frontend
            DataUtils["Shared Data Utilities\nlib/data.ts, lib/utils.ts"]:::frontend
        end

        subgraph "UI Component Library"
            AddTx["Transaction Form\naddTransactionForm.tsx"]:::frontend
            BarGraph["Bar Graph Component\nbargraph.tsx"]:::frontend
            LineChart["Line Chart Component\nlinechart.tsx"]:::frontend
            UIPrimitives["Core UI Primitives\nui/button.tsx\nui/input.tsx\nui/toast.tsx"]:::frontend
            KokoUI["KokonutUI Components\nkokonutui/*"]:::frontend
            MagicUI["MagicUI Components\nmagicui/*"]:::frontend
            Tutorial["Tutorial & Example Components\ntutorial/*"]:::frontend
        end
    end

    %% Supabase Services
    subgraph "Supabase Services"
        AuthService["Auth Service"]:::supabase
        Postgres["Postgres Database"]:::supabase
        Storage["Storage"]:::supabase
        EdgeFuncs["Edge Functions"]:::supabase
    end

    %% External Services
    ExternalSMTP["External SMTP Provider"]:::external

    %% Connections
    Browser -->|"HTTP SSR/SSG"| LayoutRoot
    LayoutRoot --> EntryPage
    EntryPage --> Providers
    Providers --> SignIn
    Providers --> SignUp
    Providers --> Forgot
    Providers --> DashboardHome
    SignIn -->|"supabase-js SDK"| ClientSDK
    SignUp -->|"supabase-js SDK"| ClientSDK
    Forgot -->|"supabase-js SDK"| ClientSDK
    DashboardHome --> Actions
    DashboardHome --> ClientSDK
    TransactionsPage --> ClientSDK
    ResetPwdPage --> ServerSDK

    Actions -->|"@supabase/supabase-node"| ServerSDK
    Mil1 --> ServerSDK
    Mil2 --> ServerSDK

    ClientSDK --> AuthService
    ClientSDK --> Postgres
    ClientSDK --> Storage

    ServerSDK --> AuthService
    ServerSDK --> Postgres
    ServerSDK --> Storage

    AuthService -->|triggers email| ExternalSMTP

    %% Click Events
    click LayoutRoot "https://github.com/faizm10/spendsmart/blob/main/frontend/app/layout.tsx"
    click EntryPage "https://github.com/faizm10/spendsmart/blob/main/frontend/app/page.tsx"
    click SignIn "https://github.com/faizm10/spendsmart/blob/main/frontend/app/(auth-pages)/sign-in/page.tsx"
    click SignUp "https://github.com/faizm10/spendsmart/blob/main/frontend/app/(auth-pages)/sign-up/page.tsx"
    click Forgot "https://github.com/faizm10/spendsmart/blob/main/frontend/app/(auth-pages)/forgot-password/page.tsx"
    click AuthCallback "https://github.com/faizm10/spendsmart/blob/main/frontend/app/auth/callback/route.ts"
    click DashboardHome "https://github.com/faizm10/spendsmart/blob/main/frontend/app/dashboard/page.tsx"
    click TransactionsPage "https://github.com/faizm10/spendsmart/blob/main/frontend/app/dashboard/transactions/page.tsx"
    click ResetPwdPage "https://github.com/faizm10/spendsmart/blob/main/frontend/app/dashboard/reset-password/page.tsx"
    click Providers "https://github.com/faizm10/spendsmart/blob/main/frontend/app/providers.tsx"
    click Actions "https://github.com/faizm10/spendsmart/blob/main/frontend/app/actions.ts"
    click Mil1 "https://github.com/faizm10/spendsmart/blob/main/frontend/middleware.ts"
    click Mil2 "https://github.com/faizm10/spendsmart/blob/main/frontend/utils/supabase/middleware.ts"
    click ClientSDK "https://github.com/faizm10/spendsmart/blob/main/frontend/utils/supabase/client.ts"
    click ServerSDK "https://github.com/faizm10/spendsmart/blob/main/frontend/utils/supabase/server.ts"
    click EnvCheck "https://github.com/faizm10/spendsmart/blob/main/frontend/utils/supabase/check-env-vars.ts"
    click UseToast "https://github.com/faizm10/spendsmart/blob/main/frontend/hooks/use-toast.ts"
    click UseMobile "https://github.com/faizm10/spendsmart/blob/main/frontend/hooks/use-mobile.tsx"
    click DataUtils "https://github.com/faizm10/spendsmart/blob/main/frontend/lib/data.ts"
    click DataUtils "https://github.com/faizm10/spendsmart/blob/main/frontend/lib/utils.ts"
    click AddTx "https://github.com/faizm10/spendsmart/blob/main/frontend/components/addTransactionForm.tsx"
    click BarGraph "https://github.com/faizm10/spendsmart/blob/main/frontend/components/charts/bargraph.tsx"
    click LineChart "https://github.com/faizm10/spendsmart/blob/main/frontend/components/charts/linechart.tsx"
    click UIPrimitives "https://github.com/faizm10/spendsmart/blob/main/frontend/components/ui/button.tsx"
    click UIPrimitives "https://github.com/faizm10/spendsmart/blob/main/frontend/components/ui/input.tsx"
    click UIPrimitives "https://github.com/faizm10/spendsmart/blob/main/frontend/components/ui/toast.tsx"
    click KokoUI "https://github.com/faizm10/spendsmart/tree/main/frontend/components/kokonutui/"
    click MagicUI "https://github.com/faizm10/spendsmart/tree/main/frontend/components/magicui/"
    click Tutorial "https://github.com/faizm10/spendsmart/tree/main/frontend/components/tutorial/"
    click ConfigFiles "https://github.com/faizm10/spendsmart/blob/main/frontend/next.config.ts"

    %% Styles
    classDef frontend fill:#cfe2ff,stroke:#0366d6,stroke-width:1px;
    classDef supabase fill:#d1e7dd,stroke:#116530,stroke-width:1px;
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:1px;
```
