# sidedishjob/kuralis architecture

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

- Interactive diagram: https://gitdiagram.com/sidedishjob/kuralis
- Repository: https://github.com/sidedishjob/kuralis

## Overview

##### Project Type and Purpose
- This is a full-stack web application (“furniture register & maintenance”) built with Next.js (App Router) on the front end and Supabase (Postgres, Auth, Storage) on the back end. It offers SSR content, dynamic routes, RESTful API routes, image uploads, and secure auth.

##### File Structure Highlights
- Top level:
- src/app → Next.js App Router pages and API routes under `/api/*`.
- components, contexts, hooks → UI components, state management, data-fetch hooks.
- lib → Shared utilities, API fetcher, server-side wrappers, Supabase clients, error handling.
- supabase → SQL migrations.
- Config files: next.config.ts, tailwind.config.mjs, vercel.json, GitHub Actions workflow.

##### Main Components
a. Frontend (Next.js App)
- App Router (SSR pages, client hydration)
- UI component library (shadcn/ui, Radix UI, Tailwind)
- React Context & Custom Hooks for state & data fetching (SWR)
b. Backend/API
- Next.js API Routes (`/src/app/api/.../route.ts`)
- Shared business-logic modules in `lib/server/*` and `lib/api/route.ts`
c. Database & Storage
- Supabase PostgreSQL: tables for users, furniture, maintenance, metadata (see supabase/migrations)
- Supabase Storage: image upload bucket + CDN
- RLS & Policies for multi-tenant data security
d. Authentication & Email
- Supabase Auth (email/password + OAuth)
- nodemailer for transactional emails (password reset, contact form)
e. CI/CD & Hosting
- GitHub Actions (lint, tests, build, explicit Vercel CLI deploy)
- Vercel for hosting the Next.js app
f. External & Utility Services
- date-fns for cycle calculation
- SWR for client caching
- Zod + React Hook Form for form validation
- GTag analytics, error logging (client and server)

##### Relationships & Data Flows
- User → Next.js Frontend (SSR/CSR pages)
- Frontend → Next.js API Routes → lib/server → Supabase DB / Storage
- Frontend (SWR/React Query) → Supabase directly (via supabase client hooks) for some data
- Next.js App’s getServerSideProps (SSR) → Supabase to pre-render critical pages
- Next.js API Routes → nodemailer for email sending
- GitHub Actions → Vercel CLI → Vercel Environment

##### Architectural Patterns & Design Principles
- Separation of Concerns: UI vs data-fetch hooks vs API logic vs DB schema
- Modular Routing: file-based routing for pages and nested API routes
- SSR + Hydration: preloaded furniture list + client filtering
- RLS at the database layer: isolates user data per session
- Shared API layer: `lib/api/route.ts` standardizes error handling & responses

- Caching or CDN layer between Storage and Frontend
- Analytics & Error Logging flow to any external service (GTag)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        U["User's Browser"]:::external
        App["Next.js App (SSR/CSR, App Router)"]:::frontend
        subgraph "UI & State"
            direction TB
            UIlib["UI Component Library"]:::frontend
            Features["Feature UI Components"]:::frontend
            LayoutNav["Global Layout & Navigation"]:::frontend
            Context["React Context & State Management"]:::frontend
            Hooks["Custom Data-Fetch & Utility Hooks"]:::frontend
        end
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        APIRoutes["Next.js API Routes"]:::backend
        SharedAPI["Shared API Layer & Error Handling"]:::backend
        BizLogic["Business-Logic Modules"]:::backend
        SMTP["nodemailer SMTP Service"]:::external
        ErrorLogAPI["Client-Side Error Logging Endpoint"]:::backend
        ContactAPI["Contact Form & Email API"]:::backend
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        supaAuth["Supabase Auth"]:::database
        supaDB["Supabase PostgreSQL"]:::database
        supaStorage["Supabase Storage (Images & CDN)"]:::database
        Migrations["Supabase Migrations"]:::database
    end

    %% External Services
    subgraph "External & Utilities"
        direction TB
        Analytics["GTag Analytics & Pageview Listener"]:::external
        Validation["Validation Schemas (Zod)"]:::backend
    end

    %% Infra Layer
    subgraph "CI/CD & Hosting"
        direction TB
        CI["GitHub Actions"]:::ci
        Vercel["Vercel Hosting & CLI"]:::ci
        Configs["Next.js & Tailwind Configs"]:::ci
    end

    %% Presentation Connections
    U -->|"HTTP(S)"| App
    App -->|"renders via App Router"| UIlib
    App -->|"renders"| Features
    App -->|"wraps"| LayoutNav
    App -->|"provides via Provider"| Context
    App -->|"calls"| Hooks

    %% Data Fetch Flows
    Hooks -->|"supabase-js"| supaDB
    Hooks -->|"supabase-js"| supaStorage
    App -->|"SSR Fetch via getServerSideProps"| supaDB

    %% API Flows
    App -->|"REST API"| APIRoutes
    APIRoutes -->|"uses"| SharedAPI
    SharedAPI -->|"imports"| Validation
    APIRoutes -->|"executes"| BizLogic
    BizLogic -->|"SQL Queries"| supaDB
    BizLogic -->|"Storage API"| supaStorage
    APIRoutes -->|"sends email"| SMTP
    APIRoutes -->|"error log"| ErrorLogAPI
    ContactAPI -->|"POST Contact"| SMTP

    %% Analytics
    App -->|"pageview events"| Analytics

    %% Auth Flows
    App -->|"Auth pages/callbacks"| supaAuth
    supaAuth -->|"JWT & Sessions"| App

    %% Infra Flows
    CI -->|"trigger deploy"| Vercel
    Vercel -->|"hosts"| App
    CI -->|"uses configs"| Configs

    %% Migrations
    Migrations -->|"db schema"| supaDB

    %% Click Events
    click App "https://github.com/sidedishjob/kuralis/tree/main/src/app"
    click UIlib "https://github.com/sidedishjob/kuralis/tree/main/src/components/ui"
    click UIlib "https://github.com/sidedishjob/kuralis/tree/main/src/components/common/ui"
    click Features "https://github.com/sidedishjob/kuralis/tree/main/src/components/features/furniture"
    click LayoutNav "https://github.com/sidedishjob/kuralis/tree/main/src/components/common/layout"
    click LayoutNav "https://github.com/sidedishjob/kuralis/tree/main/src/components/common/navigation"
    click Context "https://github.com/sidedishjob/kuralis/blob/main/src/contexts/AuthContext.tsx"
    click Context "https://github.com/sidedishjob/kuralis/blob/main/src/contexts/AuthProvider.tsx"
    click Hooks "https://github.com/sidedishjob/kuralis/tree/main/src/hooks"
    click Hooks "https://github.com/sidedishjob/kuralis/blob/main/src/lib/supabase/hooks/useSupabaseClient.ts"
    click APIRoutes "https://github.com/sidedishjob/kuralis/tree/main/src/app/api"
    click SharedAPI "https://github.com/sidedishjob/kuralis/blob/main/src/lib/api/route.ts"
    click SharedAPI "https://github.com/sidedishjob/kuralis/blob/main/src/lib/errors/ApiError.ts"
    click SharedAPI "https://github.com/sidedishjob/kuralis/blob/main/src/lib/utils/handleApiError.ts"
    click BizLogic "https://github.com/sidedishjob/kuralis/blob/main/src/lib/server/furniture.ts"
    click BizLogic "https://github.com/sidedishjob/kuralis/blob/main/src/lib/server/maintenance.ts"
    click BizLogic "https://github.com/sidedishjob/kuralis/blob/main/src/lib/server/furnitureMeta.ts"
    click BizLogic "https://github.com/sidedishjob/kuralis/blob/main/src/lib/server/getAllMaintenanceSummary.ts"
    click Validation "https://github.com/sidedishjob/kuralis/blob/main/src/lib/validation/authSchema.ts"
    click Validation "https://github.com/sidedishjob/kuralis/blob/main/src/lib/validation/furnitureSchema.ts"
    click Validation "https://github.com/sidedishjob/kuralis/blob/main/src/lib/validation/maintenanceSchema.ts"
    click Validation "https://github.com/sidedishjob/kuralis/blob/main/src/lib/validation/contactSchema.ts"
    click SMTP "https://github.com/sidedishjob/kuralis/blob/main/src/app/contact/ContactForm.tsx"
    click ContactAPI "https://github.com/sidedishjob/kuralis/blob/main/src/app/api/contact/route.ts"
    click ErrorLogAPI "https://github.com/sidedishjob/kuralis/blob/main/src/app/api/log-client-error/route.ts"
    click supaDB "https://github.com/sidedishjob/kuralis/tree/main/supabase/migrations"
    click Analytics "https://github.com/sidedishjob/kuralis/blob/main/src/lib/gtag.ts"
    click Analytics "https://github.com/sidedishjob/kuralis/blob/main/src/app/_analytics/pageviewListener.tsx"
    click CI "https://github.com/sidedishjob/kuralis/blob/main/.github/workflows/ci-deploy.yml"
    click Vercel "https://github.com/sidedishjob/kuralis/blob/main/vercel.json"
    click Configs "https://github.com/sidedishjob/kuralis/blob/main/tailwind.config.mjs"
    click Configs "https://github.com/sidedishjob/kuralis/blob/main/next.config.ts"

    %% Styles
    classDef frontend fill:#e0f2ff,stroke:#0a6ebd,color:#0a6ebd;
    classDef backend fill:#e6ffe6,stroke:#2d8a2d,color:#2d8a2d;
    classDef database fill:#fff4e6,stroke:#d97706,color:#d97706;
    classDef external fill:#f3e6ff,stroke:#7c3aed,color:#7c3aed;
    classDef ci fill:#eeeeee,stroke:#6b7280,color:#374151;
```
