# rifqoooh/zoincas architecture

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

- Interactive diagram: https://gitdiagram.com/rifqoooh/zoincas
- Repository: https://github.com/rifqoooh/zoincas

## Overview

##### Project type and purpose
- This is a full-stack Next.js (App Router) web application for personal finance management (budgets, balances, categories, transactions), with both public marketing pages (src/app/(web)), authenticated user dashboard (src/app/(main)), and an admin interface (src/app/(admin)). The backend is implemented via Next.js serverless API routes (src/app/api), using Drizzle ORM for the database, Redis for caching/rate-limiting, Zod for validation, and external services like OpenAI (AI route) and Sentry (error monitoring).

##### File structure
- Top-level Next.js config and dependencies (next.config.ts, package.json, drizzle.config.ts)
- src/app directory:
- (web): static marketing pages
- (auth): authentication flows (sign-in, sign-up)
- (main): client-side dashboard pages, protected by middleware
- (admin): admin UI, protected by admin middleware
- /api/[[...route]]/_routes: modular route handlers for sessions, users, balances, budgets, categories, transactions, summaries, AI
- src/lib:
- api utilities (router creation, OpenAPI, RPC)
- auth client/server
- db schema, seeds, service functions (CRUD logic)
- redis utilities and rate-limiter
- src/hooks & src/providers: React Query hooks (queries, mutations, stores) and context providers (auth, theme, query client)
- src/components: UI component library, form and modal components, data tables, charts, sidebars
- src/middleware: page and API middleware for auth/enforcement
- src/validators: Zod schemas for API and DB

##### README for additional insights

a. Main components:
- Client (Browser)
- Next.js App (Edge + Server):
– App Router (SSR/SSR as needed)
– Page Middleware (auth, admin)
– API Router (modular route handlers)
- Business Logic Layer (src/lib/db/services, validators)
- Database (PostgreSQL/MySQL via Drizzle ORM)
- Cache/Rate-Limiter (Redis)
- External Services:
– OpenAI/Gemini API (AI route)
– Sentry (error monitoring)
– Vercel (hosting/CDN)
b. Relationships & data flows:
1. User → Browser UI → Next.js pages (rendered server-side or client-side)
2. UI actions → React Query hooks → fetch to API routes
3. API route → middleware (auth/admin) → handler → validators → DB service → Drizzle → Database
4. Handler may also call Redis for caching or rate-limiting, or call OpenAI API.
5. Errors and performance data sent to Sentry.
c. Architectural patterns & design principles:
- Layered architecture (Presentation, API, Service, Data)
- Separation of concerns: UI components vs. hooks vs. services vs. validators
- Modular API routing under Next.js App Router
- Use of middleware for cross-cutting concerns (auth, admin)
- Type safety and validation with Zod at both API and DB layers
d. Key technologies & frameworks:
- Next.js (App Router, serverless functions)
- React Query (data fetching & caching)
- Drizzle ORM (database schema & queries)
- Redis (cache & rate limiter)
- Zod (validation)
- OpenAI API (AI features)
- Sentry (monitoring)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client Layer
    Browser["Browser"]:::presentation

    %% Vercel CDN
    Vercel["Vercel/CDN"]:::external

    %% Frontend Subgraph
    subgraph "Next.js Frontend"
        NextSSR["Next.js SSR/SSG"]:::presentation
        Marketing["Marketing Pages (Public Web)"]:::presentation
        AuthFlow["Authentication Flow"]:::presentation
        Dashboard["Authenticated User Dashboard"]:::presentation
        AdminUI["Admin Interface"]:::presentation
    end

    %% API Layer
    subgraph "Next.js API"
        APIRouter["API Router Entry Point"]:::logic
        APIMW["API Middleware"]:::logic
        subgraph "Route Handlers"
            AIHandler["AI Handler"]:::logic
            SessionsHandler["Sessions Handler"]:::logic
            UsersHandler["Users Handler"]:::logic
            BalancesHandler["Balances Handler"]:::logic
            BudgetPlansHandler["Budget Plans Handler"]:::logic
            BudgetCategoriesHandler["Budget Categories Handler"]:::logic
            CategoriesHandler["Categories Handler"]:::logic
            TransactionsHandler["Transactions Handler"]:::logic
            SummariesHandler["Summaries Handler"]:::logic
        end
    end

    %% Business Logic and Validation
    Services["Business Logic / Services"]:::logic
    ValAPI["API Validators"]:::logic
    ValDB["DB Validators"]:::logic

    %% Data Layer
    DrizzleCfg["Drizzle Config"]:::logic
    DBSchema["DB Schema"]:::logic
    Redis["Redis (Cache & Rate Limiter)"]:::datastore
    Database["Database (PostgreSQL/MySQL)"]:::datastore

    %% External Services
    OpenAI["OpenAI API"]:::external
    Sentry["Sentry"]:::external

    %% Context & Providers / Hooks (Client-side)
    subgraph "Client Utilities"
        Hooks["React Query Hooks"]:::presentation
        Providers["Context & Providers"]:::presentation
    end

    %% Connections
    Browser -->|HTTP via CDN| Vercel --> NextSSR
    NextSSR -->|renders pages from| Marketing
    NextSSR -->|renders pages from| AuthFlow
    NextSSR -->|renders pages from| Dashboard
    NextSSR -->|renders pages from| AdminUI

    Browser -->|fetch/mutate via HTTP| APIRouter
    APIRouter -->|enforced by| APIMW
    APIMW -->|routes to| AIHandler
    APIMW -->|routes to| SessionsHandler
    APIMW -->|routes to| UsersHandler
    APIMW -->|routes to| BalancesHandler
    APIMW -->|routes to| BudgetPlansHandler
    APIMW -->|routes to| BudgetCategoriesHandler
    APIMW -->|routes to| CategoriesHandler
    APIMW -->|routes to| TransactionsHandler
    APIMW -->|routes to| SummariesHandler

    AIHandler -->|calls| OpenAI
    AIHandler -->|logs errors to| Sentry
    SessionsHandler -->|uses| Services
    UsersHandler -->|uses| Services
    BalancesHandler -->|uses| Services
    BudgetPlansHandler -->|uses| Services
    BudgetCategoriesHandler -->|uses| Services
    CategoriesHandler -->|uses| Services
    TransactionsHandler -->|uses| Services
    SummariesHandler -->|uses| Services

    Services -->|validates via| ValAPI
    Services -->|validates via| ValDB
    Services -->|executes ORM| DrizzleCfg
    Services -->|executes ORM| DBSchema
    Services -->|reads/writes| Database
    APIRouter -->|rate-limit/cache| Redis
    APIRouter -->|errors to| Sentry

    Browser -->|client hooks| Hooks
    Hooks -->|uses| APIRouter
    Hooks -->|wrapped by| Providers

    %% Click Events
    click Marketing "https://github.com/rifqoooh/zoincas/tree/master/src/app/(web)"
    click AuthFlow "https://github.com/rifqoooh/zoincas/tree/master/src/app/(auth)"
    click Dashboard "https://github.com/rifqoooh/zoincas/tree/master/src/app/(main)"
    click AdminUI "https://github.com/rifqoooh/zoincas/tree/master/src/app/(admin)"
    click APIRouter "https://github.com/rifqoooh/zoincas/blob/master/src/app/api/[[...route]]/route.ts"
    click AIHandler "https://github.com/rifqoooh/zoincas/tree/master/src/app/api/[[...route]]/_routes/ai"
    click SessionsHandler "https://github.com/rifqoooh/zoincas/tree/master/src/app/api/[[...route]]/_routes/sessions"
    click UsersHandler "https://github.com/rifqoooh/zoincas/tree/master/src/app/api/[[...route]]/_routes/users"
    click BalancesHandler "https://github.com/rifqoooh/zoincas/tree/master/src/app/api/[[...route]]/_routes/balances"
    click BudgetPlansHandler "https://github.com/rifqoooh/zoincas/tree/master/src/app/api/[[...route]]/_routes/budget-plans"
    click BudgetCategoriesHandler "https://github.com/rifqoooh/zoincas/tree/master/src/app/api/[[...route]]/_routes/budget-categories"
    click CategoriesHandler "https://github.com/rifqoooh/zoincas/tree/master/src/app/api/[[...route]]/_routes/categories"
    click TransactionsHandler "https://github.com/rifqoooh/zoincas/tree/master/src/app/api/[[...route]]/_routes/transactions"
    click SummariesHandler "https://github.com/rifqoooh/zoincas/tree/master/src/app/api/[[...route]]/_routes/summaries"
    click Services "https://github.com/rifqoooh/zoincas/tree/master/src/lib/db/services"
    click DrizzleCfg "https://github.com/rifqoooh/zoincas/blob/master/drizzle.config.ts"
    click DBSchema "https://github.com/rifqoooh/zoincas/blob/master/src/lib/db/schema.ts"
    click Redis "https://github.com/rifqoooh/zoincas/blob/master/src/lib/redis/index.ts"
    click ValAPI "https://github.com/rifqoooh/zoincas/tree/master/src/validators/api"
    click ValDB "https://github.com/rifqoooh/zoincas/tree/master/src/validators/db"
    click APIMW "https://github.com/rifqoooh/zoincas/tree/master/src/middleware/api"
    click Hooks "https://github.com/rifqoooh/zoincas/tree/master/src/hooks/queries"
    click Providers "https://github.com/rifqoooh/zoincas/tree/master/src/providers"

    %% Styles
    classDef presentation fill:#ADD8E6,stroke:#000
    classDef logic fill:#90EE90,stroke:#000
    classDef datastore fill:#FFA500,stroke:#000
    classDef external fill:#D3D3D3,stroke:#000
```
