# sbktckp/ekam-finance architecture

> Architecture diagram of the GitHub repository sbktckp/ekam-finance, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sbktckp/ekam-finance
- Repository: https://github.com/sbktckp/ekam-finance

## Overview

1. **High-level shape**
   - This is a **Next.js 15 App Router** application with a clear split between **public auth screens** and a **protected finance dashboard**.
   - The backend is not a separate service in this repo; **Supabase** provides authentication, database, and row-level security.

2. **Route organization**
   - The `app/(auth)` route group contains the public entry points: **login** and **signup**.
   - The `app/(dashboard)` route group contains the authenticated product areas: **dashboard home, transactions, budget, investments, goals, bills, reports, and settings**.
   - `app/layout.tsx` is the global shell, while `app/(auth)/layout.tsx` and `app/(dashboard)/layout.tsx` likely apply different page chrome for auth vs. application use.

3. **Authentication flow**
   - Auth pages live at `app/(auth)/login` and `app/(auth)/signup`.
   - `app/auth/callback/route.ts` handles the Supabase auth redirect/callback step after sign-in.
   - `middleware.ts` is the guardrail that typically enforces session-based access to protected dashboard routes and keeps unauthenticated users out of the finance workspace.

4. **Dashboard composition**
   - The dashboard area is divided into domain pages under `app/(dashboard)/dashboard/...`.
   - Some sections have dedicated view components such as `transactions-view.tsx`, `budget-view.tsx`, `goals-view.tsx`, `investments-view.tsx`, and `bills-view.tsx`, which suggests a pattern where the route file is thin and the screen logic lives in reusable page-level views.
   - `app/(dashboard)/dashboard/page.tsx` acts as the dashboard landing page, while `reports` and `settings` are separate areas with simpler page entrypoints.

5. **Server-side business actions**
   - `app/actions/` contains the main domain mutation/query layer, split by resource: **accounts, transactions, budgets, goals, investments, and bills**.
   - These are likely **Next.js Server Actions** that encapsulate database interaction and form handling, keeping data writes close to the server boundary.
   - This creates a clean separation: UI components trigger actions; actions talk to Supabase; Supabase persists and authorizes the data.

6. **Supabase integration boundary**
   - `lib/supabase/client.ts` is the browser/client-side Supabase entrypoint.
   - `lib/supabase/server.ts` is the server-side Supabase entrypoint used by actions, routes, and server-rendered code.
   - This separation matters architecturally because authentication/session handling and database access are split between client and server execution contexts.

7. **Domain UI building blocks**
   - `components/modals/` contains user-driven creation flows such as **Add Account** and **Add Transaction**.
   - `components/shared/` contains app-wide chrome and identity elements like the **sidebar** and **logo**.
   - These shared components are the structural layer around the dashboard, while the route-specific views provide the finance module content.

8. **Data model and types**
   - `types/database.ts` strongly suggests a generated Supabase schema type, which ties the frontend and actions to the actual PostgreSQL schema.
   - `types/index.ts` likely collects higher-level app types used across modules.
   - Together, these types enforce consistency between UI, server actions, and the database layer.

9. **Styling and presentation**
   - Styling is handled with **Tailwind CSS v3**, backed by `app/globals.css` and `tailwind.config.ts`.
   - The app uses a mostly component-driven UI model where pages assemble shared layout, module views, and modal interactions.

10. **Operational/runtime details**
   - `next.config.ts`, `postcss.config.mjs`, and `tsconfig.json` indicate a standard Next.js build pipeline with TypeScript strictness.
   - `public/manifest.json` suggests PWA-ish metadata or installability support, but it is not the core architecture.
   - The README states deployment targets **Vercel**, which aligns with Next.js server rendering, route handlers, and server actions.

11. **Conceptual data flow**
   - A user enters through login/signup, completes Supabase auth, and returns via the callback route.
   - Middleware and protected layouts then expose the dashboard.
   - Dashboard views render finance data by reading from Supabase, while modals and forms trigger server actions to create or update records.
   - Supabase RLS is the final authorization boundary on persisted financial data.

12. **What to show in an architecture diagram**
   - Draw three main zones: **public auth**, **protected dashboard UI**, and **Supabase backend**.
   - Place `middleware` between browser requests and protected routes.
   - Show server actions as the bridge from UI to Supabase.
   - Represent shared shell components and route-group layouts as the presentation layer around all dashboard modules.

Main entry points: [`app/(dashboard)/layout.tsx`](https://github.com/sbktckp/ekam-finance/blob/main/app/(dashboard)/layout.tsx) (Dashboard layout), [`app/actions`](https://github.com/sbktckp/ekam-finance/tree/main/app/actions) (Server actions), [`app/(dashboard)/dashboard/transactions/page.tsx`](https://github.com/sbktckp/ekam-finance/blob/main/app/(dashboard)/dashboard/transactions/page.tsx) (Transactions), [`app/(dashboard)/dashboard/budget/page.tsx`](https://github.com/sbktckp/ekam-finance/blob/main/app/(dashboard)/dashboard/budget/page.tsx) (Budget)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_public["Public auth"]
  node_node_home["Landing<br/>public page<br/>[page.tsx]"]
  node_node_auth_layout["Auth layout<br/>route layout<br/>[layout.tsx]"]
  node_node_login["Login<br/>auth page<br/>[page.tsx]"]
  node_node_signup["Signup<br/>auth page<br/>[page.tsx]"]
  node_node_callback["Auth callback<br/>route handler<br/>[route.ts]"]
end

subgraph group_group_dashboard["Protected dashboard"]
  node_node_dashboard_layout["Dashboard layout<br/>route layout<br/>[layout.tsx]"]
  node_node_dashboard_home["Dashboard home<br/>dashboard page<br/>[page.tsx]"]
  node_node_transactions["Transactions<br/>domain screen<br/>[page.tsx]"]
  node_node_budget["Budget<br/>domain screen<br/>[page.tsx]"]
  node_node_goals["Goals<br/>domain screen<br/>[page.tsx]"]
  node_node_investments["Investments<br/>domain screen<br/>[page.tsx]"]
  node_node_bills["Bills<br/>domain screen<br/>[page.tsx]"]
  node_node_reports["Reports<br/>dashboard page<br/>[page.tsx]"]
  node_node_settings["Settings<br/>dashboard page<br/>[page.tsx]"]
end

subgraph group_group_data["Data and backend"]
  node_node_actions["Server actions<br/>mutation layer"]
  node_node_supabase_client["Client Supabase<br/>client SDK<br/>[client.ts]"]
  node_node_supabase_server["Server Supabase<br/>server SDK<br/>[server.ts]"]
  node_node_types_db["Database types<br/>schema types<br/>[database.ts]"]
  node_node_types_shared["App types<br/>shared types<br/>[index.ts]"]
  node_node_middleware["Middleware<br/>request guard<br/>[middleware.ts]"]
end

subgraph group_group_ui["Shared UI"]
  node_node_sidebar["Sidebar<br/>shared chrome<br/>[sidebar.tsx]"]
  node_node_logo["Logo<br/>brand component<br/>[logo.tsx]"]
  node_node_add_account["Add account<br/>modal"]
  node_node_add_transaction["Add transaction<br/>modal"]
end

node_node_root["App shell<br/>Next.js app<br/>[layout.tsx]"]

node_node_root -->|"routes to"| node_node_home
node_node_root -->|"wraps"| node_node_auth_layout
node_node_root -->|"wraps"| node_node_dashboard_layout
node_node_auth_layout -->|"contains"| node_node_login
node_node_auth_layout -->|"contains"| node_node_signup
node_node_login -.->|"auth return"| node_node_callback
node_node_signup -.->|"auth return"| node_node_callback
node_node_middleware -->|"protects"| node_node_dashboard_layout
node_node_dashboard_layout -->|"uses"| node_node_sidebar
node_node_dashboard_layout -->|"uses"| node_node_logo
node_node_dashboard_layout -->|"contains"| node_node_dashboard_home
node_node_dashboard_layout -->|"contains"| node_node_transactions
node_node_dashboard_layout -->|"contains"| node_node_budget
node_node_dashboard_layout -->|"contains"| node_node_goals
node_node_dashboard_layout -->|"contains"| node_node_investments
node_node_dashboard_layout -->|"contains"| node_node_bills
node_node_dashboard_layout -->|"contains"| node_node_reports
node_node_dashboard_layout -->|"contains"| node_node_settings
node_node_dashboard_home -->|"opens"| node_node_add_account
node_node_transactions -->|"opens"| node_node_add_transaction
node_node_transactions -.->|"renders"| node_node_transactions
node_node_budget -.->|"renders"| node_node_budget
node_node_goals -.->|"renders"| node_node_goals
node_node_investments -.->|"renders"| node_node_investments
node_node_bills -.->|"renders"| node_node_bills
node_node_dashboard_home -->|"reads/writes"| node_node_actions
node_node_transactions -->|"reads/writes"| node_node_actions
node_node_budget -->|"reads/writes"| node_node_actions
node_node_goals -->|"reads/writes"| node_node_actions
node_node_investments -->|"reads/writes"| node_node_actions
node_node_bills -->|"reads/writes"| node_node_actions
node_node_actions -->|"uses"| node_node_supabase_server
node_node_callback -->|"uses"| node_node_supabase_server
node_node_supabase_server -.->|"typed by"| node_node_types_db
node_node_supabase_client -.->|"typed by"| node_node_types_shared
node_node_actions -.->|"typed by"| node_node_types_shared
node_node_actions -.->|"may use"| node_node_supabase_client

click node_node_root "https://github.com/sbktckp/ekam-finance/blob/main/app/layout.tsx"
click node_node_home "https://github.com/sbktckp/ekam-finance/blob/main/app/page.tsx"
click node_node_auth_layout "https://github.com/sbktckp/ekam-finance/blob/main/app/(auth)/layout.tsx"
click node_node_login "https://github.com/sbktckp/ekam-finance/blob/main/app/(auth)/login/page.tsx"
click node_node_signup "https://github.com/sbktckp/ekam-finance/blob/main/app/(auth)/signup/page.tsx"
click node_node_callback "https://github.com/sbktckp/ekam-finance/blob/main/app/auth/callback/route.ts"
click node_node_dashboard_layout "https://github.com/sbktckp/ekam-finance/blob/main/app/(dashboard)/layout.tsx"
click node_node_dashboard_home "https://github.com/sbktckp/ekam-finance/blob/main/app/(dashboard)/dashboard/page.tsx"
click node_node_transactions "https://github.com/sbktckp/ekam-finance/blob/main/app/(dashboard)/dashboard/transactions/page.tsx"
click node_node_budget "https://github.com/sbktckp/ekam-finance/blob/main/app/(dashboard)/dashboard/budget/page.tsx"
click node_node_goals "https://github.com/sbktckp/ekam-finance/blob/main/app/(dashboard)/dashboard/goals/page.tsx"
click node_node_investments "https://github.com/sbktckp/ekam-finance/blob/main/app/(dashboard)/dashboard/investments/page.tsx"
click node_node_bills "https://github.com/sbktckp/ekam-finance/blob/main/app/(dashboard)/dashboard/bills/page.tsx"
click node_node_reports "https://github.com/sbktckp/ekam-finance/blob/main/app/(dashboard)/dashboard/reports/page.tsx"
click node_node_settings "https://github.com/sbktckp/ekam-finance/blob/main/app/(dashboard)/dashboard/settings/page.tsx"
click node_node_actions "https://github.com/sbktckp/ekam-finance/tree/main/app/actions"
click node_node_supabase_client "https://github.com/sbktckp/ekam-finance/blob/main/lib/supabase/client.ts"
click node_node_supabase_server "https://github.com/sbktckp/ekam-finance/blob/main/lib/supabase/server.ts"
click node_node_types_db "https://github.com/sbktckp/ekam-finance/blob/main/types/database.ts"
click node_node_types_shared "https://github.com/sbktckp/ekam-finance/blob/main/types/index.ts"
click node_node_sidebar "https://github.com/sbktckp/ekam-finance/blob/main/components/shared/sidebar.tsx"
click node_node_logo "https://github.com/sbktckp/ekam-finance/blob/main/components/shared/logo.tsx"
click node_node_add_account "https://github.com/sbktckp/ekam-finance/blob/main/components/modals/add-account-modal.tsx"
click node_node_add_transaction "https://github.com/sbktckp/ekam-finance/blob/main/components/modals/add-transaction-modal.tsx"
click node_node_middleware "https://github.com/sbktckp/ekam-finance/blob/main/middleware.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_home,node_node_auth_layout,node_node_login,node_node_signup,node_node_callback toneBlue
class node_node_dashboard_layout,node_node_dashboard_home,node_node_transactions,node_node_budget,node_node_goals,node_node_investments,node_node_bills,node_node_reports,node_node_settings toneAmber
class node_node_actions,node_node_supabase_client,node_node_supabase_server,node_node_types_db,node_node_types_shared,node_node_middleware toneMint
class node_node_sidebar,node_node_logo,node_node_add_account,node_node_add_transaction toneRose
class node_node_root toneNeutral
```

## Components

### Public auth

Login and signup entrypoints plus auth callback handling.

- [Landing](https://github.com/sbktckp/ekam-finance/blob/main/app/page.tsx): public page · Top-level entry page for the site. · `app/page.tsx`
- [Auth layout](https://github.com/sbktckp/ekam-finance/blob/main/app/(auth)/layout.tsx): route layout · Presentation shell for public authentication screens. · `app/(auth)/layout.tsx`
- [Login](https://github.com/sbktckp/ekam-finance/blob/main/app/(auth)/login/page.tsx): auth page · Public sign-in screen. · `app/(auth)/login/page.tsx`
- [Signup](https://github.com/sbktckp/ekam-finance/blob/main/app/(auth)/signup/page.tsx): auth page · Public account creation screen. · `app/(auth)/signup/page.tsx`
- [Auth callback](https://github.com/sbktckp/ekam-finance/blob/main/app/auth/callback/route.ts): route handler · Supabase redirect callback after authentication. · `app/auth/callback/route.ts`

### Protected dashboard

Authenticated finance workspace and its domain pages.

- [Dashboard layout](https://github.com/sbktckp/ekam-finance/blob/main/app/(dashboard)/layout.tsx): route layout · Protected workspace shell for authenticated finance pages. · `app/(dashboard)/layout.tsx`
- [Dashboard home](https://github.com/sbktckp/ekam-finance/blob/main/app/(dashboard)/dashboard/page.tsx): dashboard page · Main landing page for the finance workspace. · `app/(dashboard)/dashboard/page.tsx`
- [Transactions](https://github.com/sbktckp/ekam-finance/blob/main/app/(dashboard)/dashboard/transactions/page.tsx): domain screen · Transaction list and interaction screen. · `app/(dashboard)/dashboard/transactions/page.tsx`
- [Budget](https://github.com/sbktckp/ekam-finance/blob/main/app/(dashboard)/dashboard/budget/page.tsx): domain screen · Budget management screen. · `app/(dashboard)/dashboard/budget/page.tsx`
- [Goals](https://github.com/sbktckp/ekam-finance/blob/main/app/(dashboard)/dashboard/goals/page.tsx): domain screen · Financial goals screen. · `app/(dashboard)/dashboard/goals/page.tsx`
- [Investments](https://github.com/sbktckp/ekam-finance/blob/main/app/(dashboard)/dashboard/investments/page.tsx): domain screen · Investment tracking screen. · `app/(dashboard)/dashboard/investments/page.tsx`
- [Bills](https://github.com/sbktckp/ekam-finance/blob/main/app/(dashboard)/dashboard/bills/page.tsx): domain screen · Bills and recurring payments screen. · `app/(dashboard)/dashboard/bills/page.tsx`
- [Reports](https://github.com/sbktckp/ekam-finance/blob/main/app/(dashboard)/dashboard/reports/page.tsx): dashboard page · Reporting and analytics entrypoint. · `app/(dashboard)/dashboard/reports/page.tsx`
- [Settings](https://github.com/sbktckp/ekam-finance/blob/main/app/(dashboard)/dashboard/settings/page.tsx): dashboard page · Application settings entrypoint. · `app/(dashboard)/dashboard/settings/page.tsx`

### Data and backend

Server actions, Supabase integration, and shared domain types.

- [Server actions](https://github.com/sbktckp/ekam-finance/tree/main/app/actions): mutation layer · Next.js server actions for domain reads and writes. · `app/actions`
- [Client Supabase](https://github.com/sbktckp/ekam-finance/blob/main/lib/supabase/client.ts): client SDK · Browser-side Supabase entrypoint. · `lib/supabase/client.ts`
- [Server Supabase](https://github.com/sbktckp/ekam-finance/blob/main/lib/supabase/server.ts): server SDK · Server-side Supabase entrypoint for actions and routes. · `lib/supabase/server.ts`
- [Database types](https://github.com/sbktckp/ekam-finance/blob/main/types/database.ts): schema types · Generated Supabase database schema typings. · `types/database.ts`
- [App types](https://github.com/sbktckp/ekam-finance/blob/main/types/index.ts): shared types · Cross-cutting application type definitions. · `types/index.ts`
- [Middleware](https://github.com/sbktckp/ekam-finance/blob/main/middleware.ts): request guard · Session guard and route protection boundary. · `middleware.ts`

### Shared UI

Reusable chrome and modal components used across the app.

- [Sidebar](https://github.com/sbktckp/ekam-finance/blob/main/components/shared/sidebar.tsx): shared chrome · Primary navigation shell for the dashboard. · `components/shared/sidebar.tsx`
- [Logo](https://github.com/sbktckp/ekam-finance/blob/main/components/shared/logo.tsx): brand component · App identity and branding element. · `components/shared/logo.tsx`
- [Add account](https://github.com/sbktckp/ekam-finance/blob/main/components/modals/add-account-modal.tsx): modal · Flow for creating a new account. · `components/modals/add-account-modal.tsx`
- [Add transaction](https://github.com/sbktckp/ekam-finance/blob/main/components/modals/add-transaction-modal.tsx): modal · Flow for creating a new transaction. · `components/modals/add-transaction-modal.tsx`

### Other components

- [App shell](https://github.com/sbktckp/ekam-finance/blob/main/app/layout.tsx): Next.js app · Global App Router shell and route entrypoint coordination. · `app/layout.tsx`

## Connections

- App shell → Landing: routes to · Top-level app entrypoint.
- App shell → Auth layout: wraps · Applies shared auth-route shell.
- App shell → Dashboard layout: wraps · Applies protected workspace shell.
- Auth layout → Login: contains · Public login screen.
- Auth layout → Signup: contains · Public signup screen.
- Login → Auth callback: auth return · Authentication redirect completes here.
- Signup → Auth callback: auth return · Authentication redirect completes here.
- Middleware → Dashboard layout: protects · Prevents unauthenticated access to workspace routes.
- Dashboard layout → Sidebar: uses · Dashboard navigation chrome.
- Dashboard layout → Logo: uses · Brand element in app shell.
- Dashboard layout → Dashboard home: contains · Workspace landing page.
- Dashboard layout → Transactions: contains · Finance module screen.
- Dashboard layout → Budget: contains · Finance module screen.
- Dashboard layout → Goals: contains · Finance module screen.
- Dashboard layout → Investments: contains · Finance module screen.
- Dashboard layout → Bills: contains · Finance module screen.
- Dashboard layout → Reports: contains · Analytics entrypoint.
- Dashboard layout → Settings: contains · Settings entrypoint.
- Dashboard home → Add account: opens · Account creation flow from dashboard.
- Transactions → Add transaction: opens · Transaction creation flow.
- Transactions → Transactions: renders · Dedicated view component supports the page.
- Budget → Budget: renders · Dedicated view component supports the page.
- Goals → Goals: renders · Dedicated view component supports the page.
- Investments → Investments: renders · Dedicated view component supports the page.
- Bills → Bills: renders · Dedicated view component supports the page.
- Dashboard home → Server actions: reads/writes · Dashboard data operations go through server actions.
- Transactions → Server actions: reads/writes · Transaction operations go through server actions.
- Budget → Server actions: reads/writes · Budget operations go through server actions.
- Goals → Server actions: reads/writes · Goals operations go through server actions.
- Investments → Server actions: reads/writes · Investment operations go through server actions.
- Bills → Server actions: reads/writes · Bills operations go through server actions.
- Server actions → Server Supabase: uses · Server-side database and auth access.
- Auth callback → Server Supabase: uses · Completes auth flow on the server.
- Server Supabase → Database types: typed by · Database schema typings guide server access.
- Client Supabase → App types: typed by · Client code shares app-level types.
- Server actions → App types: typed by · Actions share application types.
- Server actions → Client Supabase: may use · Client-facing auth or session helpers as needed.