# habibwritescode/penny-wise architecture

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

- Interactive diagram: https://gitdiagram.com/habibwritescode/penny-wise
- Repository: https://github.com/habibwritescode/penny-wise

## Overview

##### Project Type and Purpose
- Pennywise is a single-page application (SPA) built on Next.js + TypeScript.
- Purpose: Personal finance management (transactions, budgets, pots, recurring bills).
- Key users: End-users in a browser.

##### File Structure
- src/pages – Next.js route handlers:
– /_app.tsx, /_document.tsx (global setup)
– /api/hello.ts (API stub)
– UI pages under /, /login, /sign-up, /budgets, /pots, /transactions, /recurring-bills
- src/components – Reusable UI building blocks (Shadcn + Tailwind).
- src/modules – Feature modules (auth, budgets, overview, pots, transactions, recurring-bills) each with page, components, utils.
- src/lib/store – Zustand global state slices (auth, budget, pot, transaction).
- src/utils – Shared utility functions (formatters, schemas with zod).
- Config & tooling: next.config.mjs, tailwind.config.ts, tsconfig.json, ESLint, PostCSS.

##### Extract Architecture Insights from README
- UI: Next.js + React + Shadcn + Tailwind.
- State: Zustand for client-side state.
- Forms: React Hook Form + zod for validation.
- No explicit database code present – likely calls an external API or serverless functions.

##### Main Components
A. Client Browser
B. Next.js Frontend (Pages + Components)
C. State Management (Zustand Store)
D. API Layer (Next.js API Routes under /pages/api)
E. (Optional) Data Storage – e.g., database or third-party finance API
F. External Services – Authentication provider, analytics, etc.

##### Relationships and Data Flows
- Browser → Next.js pages/components: HTTP(S) requests and client-side routing.
- Pages ↔ Zustand store: Local read/write for UI state.
- Pages → API routes: RESTful calls for CRUD operations (transactions, budgets, pots, bills).
- API routes → Database or External Service: data persistence or integration.
- Components → Form Library (React Hook Form + zod): data entry and validation.

##### Architectural Patterns and Principles
- Feature-based modular structure (src/modules).
- Separation of concerns:
– UI layer (components)
– Business logic (module utils + store slices)
– API layer (serverless functions)
- Unidirectional data flow: API → store → UI, UI actions → store → API.
- Validation at boundary: zod schemas in forms and API inputs.

##### Technologies & Frameworks to Annotate
- Next.js (SSR, SSG, API routes)
- React + TypeScript
- Zustand (state slices)
- Tailwind CSS + Shadcn UI components
- React Hook Form + zod
- Build configs: PostCSS, ESLint, tsconfig

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side
    subgraph "Client Side"
        direction TB
        Browser["Browser"]:::external

        subgraph "Next.js Frontend"
            direction TB
            Pages["src/pages (Next.js Pages)"]:::ui
            App["_app.tsx"]:::ui
            Document["_document.tsx"]:::ui
            click Pages "https://github.com/habibwritescode/penny-wise/tree/main/src/pages"
            click App "https://github.com/habibwritescode/penny-wise/blob/main/src/pages/_app.tsx"
            click Document "https://github.com/habibwritescode/penny-wise/blob/main/src/pages/_document.tsx"

            subgraph "Feature Modules"
                direction TB
                AuthPage["Auth Module"]:::ui
                BudgetsPage["Budgets Module"]:::ui
                OverviewPage["Overview Module"]:::ui
                PotsPage["Pots Module"]:::ui
                TransactionsPage["Transactions Module"]:::ui
                RecurringBillsPage["Recurring Bills Module"]:::ui
                click AuthPage "https://github.com/habibwritescode/penny-wise/tree/main/src/modules/auth"
                click BudgetsPage "https://github.com/habibwritescode/penny-wise/tree/main/src/modules/budgets"
                click OverviewPage "https://github.com/habibwritescode/penny-wise/tree/main/src/modules/overview"
                click PotsPage "https://github.com/habibwritescode/penny-wise/tree/main/src/modules/pots"
                click TransactionsPage "https://github.com/habibwritescode/penny-wise/tree/main/src/modules/transactions"
                click RecurringBillsPage "https://github.com/habibwritescode/penny-wise/tree/main/src/modules/recurring-bills"
            end

            subgraph "Shared UI Components"
                direction TB
                UIPrimitives["src/components/ui"]:::ui
                BuildingBlocks["src/components"]:::ui
                Layouts["src/components/layout"]:::ui
                click UIPrimitives "https://github.com/habibwritescode/penny-wise/tree/main/src/components/ui"
                click BuildingBlocks "https://github.com/habibwritescode/penny-wise/tree/main/src/components"
                click Layouts "https://github.com/habibwritescode/penny-wise/tree/main/src/components/layout"
            end

            subgraph "State Management (Zustand)"
                direction TB
                StoreRoot["store.ts"]:::state
                AuthSlice["auth.ts"]:::state
                BudgetSlice["budget.ts"]:::state
                PotSlice["pot.ts"]:::state
                TransactionSlice["transaction.ts"]:::state
                click StoreRoot "https://github.com/habibwritescode/penny-wise/blob/main/src/lib/store/store.ts"
                click AuthSlice "https://github.com/habibwritescode/penny-wise/blob/main/src/lib/store/slices/auth.ts"
                click BudgetSlice "https://github.com/habibwritescode/penny-wise/blob/main/src/lib/store/slices/budget.ts"
                click PotSlice "https://github.com/habibwritescode/penny-wise/blob/main/src/lib/store/slices/pot.ts"
                click TransactionSlice "https://github.com/habibwritescode/penny-wise/blob/main/src/lib/store/slices/transaction.ts"
            end

            subgraph "Utilities"
                direction TB
                SharedUtils["src/utils"]:::external
                LibUtils["src/lib/utils.ts"]:::external
                click SharedUtils "https://github.com/habibwritescode/penny-wise/tree/main/src/utils"
                click LibUtils "https://github.com/habibwritescode/penny-wise/blob/main/src/lib/utils.ts"
            end

            subgraph "Public Assets"
                direction TB
                Assets["public/assets"]:::external
                click Assets "https://github.com/habibwritescode/penny-wise/tree/main/public/assets"
            end
        end

        Browser -->|"renders"| Pages
        Pages -->|"uses"| UIPrimitives
        Pages -->|"imports"| BuildingBlocks
        Pages -->|"dispatches"| StoreRoot
        Pages -->|"calls API"| API["API Layer"]:::api
    end

    %% Server Side
    subgraph "Server Side"
        direction TB
        subgraph "Next.js API Routes"
            direction TB
            APIHello["hello.ts"]:::api
            click APIHello "https://github.com/habibwritescode/penny-wise/blob/main/src/pages/api/hello.ts"
            APIHello -->|"reads/writes"| Database
            APIHello -->|"integrates"| ExternalService
        end

        Database[(Database)]:::external
        ExternalService[("External Services")]:::external
    end

    %% Data Flow
    API -->|"response"| Pages

    %% Styles
    classDef ui fill:#cce5ff,stroke:#3399ff,color:#000
    classDef state fill:#d4edda,stroke:#28a745,color:#000
    classDef api fill:#fff3cd,stroke:#ffc107,color:#000
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#000
```
