# n1sp/kakei-lite architecture

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

- Interactive diagram: https://gitdiagram.com/n1sp/kakei-lite
- Repository: https://github.com/n1sp/kakei-lite

## Overview

##### Project type and purpose
- kakei-lite is a full-stack, personal finance (家計簿) web application built with Next.js and TypeScript.
- The user interface is implemented with shadcn/ui components.
- The backend is currently implemented as Next.js API routes (serverless functions) that speak REST, with a SQLite store via Supabase Client.

##### File structure
Top-level directories and their roles:
- src/app: Next.js App Router pages, layouts, CSS entrypoint.
- app/api/expenses → Serverless endpoints (GET, POST, PUT, DELETE)
- app/expense/* → UI pages: dashboard, additional expense pages
- app/notes → notes feature page
- src/components: Reusable UI elements (badge, button, table, etc.)
- src/features/expense: Domain logic for “expense” feature
- api/client.ts, endpoint.ts → thin client wrappers for REST calls
- components → feature-specific UI (ExpenseList, ExpenseSummaryCard)
- hooks/useExpenses.ts → custom React hooks for data fetching
- src/lib: Shared utilities
- supabaseClient.ts → initializes Supabase client for SQLite
- utils.ts → general helper functions
- src/utils: Formatting helpers
- Configuration files: next.config.ts (Next.js), tsconfig.json, eslint, postcss

##### README for additional insights
- Architecture described as “Frontend and Backend separated”, REST API
- Future migration: backend will move to Spring Boot + PostgreSQL, Dockerized
- Current DB: SQLite via Supabase client

##### Main components and their interactions
a. Next.js Frontend (React + shadcn/ui)
b. Next.js Serverless API (app/api/expenses routes)
c. Data Access Layer (supabaseClient → SQLite)
d. Browser (client) communicating via fetch or React Query to API
e. Future External Services: Spring Boot REST API, PostgreSQL, Docker

##### Architectural patterns and design principles
- App Router (Next.js 13) separating pages/layouts and API routes
- Feature-based module decomposition under src/features/expense
- Client-server separation within same repo (monorepo style)
- Custom hooks for data fetching (separation of concerns)
- Shared UI library (shadcn/ui) and utility modules

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        Browser["Browser"]:::external
        AppRouter["Next.js App Router"]:::frontend
        SharedUILib["shadcn/ui Components"]:::frontend
        RootPage["/app/page.tsx"]:::frontend
        Layout["/app/layout.tsx"]:::frontend
        GlobalsCSS["/app/globals.css"]:::frontend
        ExpenseDashboardPage["/app/expense/dashboard/page.tsx"]:::frontend
        ExpenseDataTable["/app/expense/dashboard/dataTable.tsx"]:::frontend
        AdditionalExpensePage["/app/expense/additional/page.tsx"]:::frontend
        NotesPage["/app/notes/page.tsx"]:::frontend

        ExpenseAPIClient["src/features/expense/api/client.ts"]:::frontend
        ExpenseAPIEndpoint["src/features/expense/api/endpoint.ts"]:::frontend
        ExpenseList["ExpenseList.tsx"]:::frontend
        ExpenseSummaryCard["ExpenseSummaryCard.tsx"]:::frontend
        ExpenseTableColumns["ExpenseTableColumns.tsx"]:::frontend
        UseExpenses["useExpenses.ts"]:::frontend
        FeatureTypes["types.ts / constants.ts"]:::frontend
        FeatureUtils["utils.ts"]:::frontend

        Browser -->|"renders"| AppRouter
        AppRouter --> RootPage
        AppRouter --> Layout
        AppRouter --> GlobalsCSS
        AppRouter --> ExpenseDashboardPage
        ExpenseDashboardPage --> ExpenseDataTable
        AppRouter --> AdditionalExpensePage
        AppRouter --> NotesPage

        ExpenseDashboardPage --> UseExpenses
        ExpenseDashboardPage --> ExpenseList
        ExpenseDashboardPage --> ExpenseSummaryCard
        ExpenseDashboardPage --> ExpenseTableColumns
        UseExpenses --> ExpenseAPIClient
        ExpenseAPIClient --> ExpenseAPIEndpoint
        ExpenseList --> FeatureTypes
        ExpenseSummaryCard --> FeatureTypes
        ExpenseList --> FeatureUtils

        AppRouter -.-> SharedUILib
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        APIRoutesList["/app/api/expenses/route.ts"]:::backend
        APIRoutesID["/app/api/expenses/[id]/route.ts"]:::backend
        SupabaseClient["src/lib/supabaseClient.ts"]:::backend
        LibUtils["src/lib/utils.ts"]:::backend

        Browser -->|GET/POST /api/expenses| APIRoutesList
        Browser -->|GET/PUT/DELETE /api/expenses/:id| APIRoutesID
        APIRoutesList --> SupabaseClient
        APIRoutesID --> SupabaseClient
        APIRoutesList --> LibUtils
        APIRoutesID --> LibUtils
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        SQLiteDB["SQLite (via Supabase)"]:::database
        FutureService["Spring Boot + PostgreSQL (Future)"]:::future
        SupabaseClient --> SQLiteDB
        FutureService -.-> SQLiteDB
    end

    %% Click Events
    click RootPage "https://github.com/n1sp/kakei-lite/blob/main/src/app/page.tsx"
    click Layout "https://github.com/n1sp/kakei-lite/blob/main/src/app/layout.tsx"
    click GlobalsCSS "https://github.com/n1sp/kakei-lite/blob/main/src/app/globals.css"
    click ExpenseDashboardPage "https://github.com/n1sp/kakei-lite/blob/main/src/app/expense/dashboard/page.tsx"
    click ExpenseDataTable "https://github.com/n1sp/kakei-lite/blob/main/src/app/expense/dashboard/dataTable.tsx"
    click AdditionalExpensePage "https://github.com/n1sp/kakei-lite/blob/main/src/app/expense/additional/page.tsx"
    click NotesPage "https://github.com/n1sp/kakei-lite/blob/main/src/app/notes/page.tsx"
    click SharedUILib "https://github.com/n1sp/kakei-lite/tree/main/src/components/ui"
    click APIRoutesList "https://github.com/n1sp/kakei-lite/blob/main/src/app/api/expenses/route.ts"
    click APIRoutesID "https://github.com/n1sp/kakei-lite/blob/main/src/app/api/expenses/[id]/route.ts"
    click SupabaseClient "https://github.com/n1sp/kakei-lite/blob/main/src/lib/supabaseClient.ts"
    click LibUtils "https://github.com/n1sp/kakei-lite/blob/main/src/lib/utils.ts"
    click ExpenseAPIClient "https://github.com/n1sp/kakei-lite/blob/main/src/features/expense/api/client.ts"
    click ExpenseAPIEndpoint "https://github.com/n1sp/kakei-lite/blob/main/src/features/expense/api/endpoint.ts"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#005B99,color:#000;
    classDef backend fill:#DBF4C6,stroke:#4B8B31,color:#000;
    classDef database fill:#FFE5B4,stroke:#CC8400,color:#000;
    classDef future fill:#F5D0A9,stroke:#D2691E,color:#000;
    classDef external fill:#EEEEEE,stroke:#888888,color:#000;
```
