# naiplawan/pos-retail-shop architecture

> Architecture diagram of the GitHub repository naiplawan/pos-retail-shop, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/naiplawan/pos-retail-shop
- Repository: https://github.com/naiplawan/pos-retail-shop

## Overview

##### Project type and purpose
- This is a full-stack retail price-tracking application with two delivery modes:
- Web (Next.js + React + TailwindCSS)
- Desktop (Electron shell wrapping the same Next.js app)

##### File structure (key directories)
- app/
- Next.js 13 “app router” directory with pages (layout.tsx, page.tsx, checklist pages) and API routes under app/api (prices, checklist, summary).
- components/
- Reusable React components (dashboard, charts, tables) and an internal UI library under components/ui (Radix-based controls).
- electron/
- Electron main and preload scripts that spin up a desktop shell hosting the Next.js app.
- lib/
- Database connectors (lib/database-electron.ts) using Prisma + Supabase, PDF-generation utilities (lib/pdf-document.tsx, jsPDF wrappers), export logic.
- hooks/
- Custom React hooks (use-mobile, use-toast).
- types/
- TypeScript definitions (electron, domain models).

##### README for technical stack and flow
- Frontend: Next.js + React + Tailwind + RadixUI + Chart.js/Recharts
- API & Data: Next.js API routes → Prisma ORM → Supabase
- PDF export: React-PDF + jsPDF
- Desktop: Electron → serves local Next.js endpoint; uses IPC via preload.js

a. Main components
- Clients:
– Web Browser (Next.js SSR/CSR pages)
– Electron Desktop (Electron Main + Preload + Next.js UI in a BrowserWindow)
- Backend/API: Next.js API Routes (app/api/\*)
- Database: Supabase (PostgreSQL) accessed via Prisma
- PDF/Export Service: React-PDF/jsPDF library invoked in the frontend
- Utility Layer: lib/ functions (database-electron, export, utils)
- External Services: Supabase (Auth & DB), optionally analytics or storage if added

b. Relationships and interactions
- Web/Electron UI → HTTP calls to Next.js API → CRUD operations on Supabase
- Electron Main ↔ Preload.js ↔ Next.js UI (IPC channel for native OS hooks or filesystem operations)
- Next.js API → Prisma client → Supabase
- UI components → Chart.js/Recharts for rendering data
- UI export features → lib/pdf-document.tsx → jsPDF to generate & download PDF

c. Architectural patterns & design principles
- Layered architecture: Presentation (React UI) → Application/API (Next.js Routes) → Data Layer (Prisma → Supabase)
- Component-based UI with a design system (components/ui)
- Single code-base deployed to both Web and Electron targets
- Separation of concerns: hooks/ for reusable logic, lib/ for utilities, API routes for business logic

d. Technologies & frameworks to annotate
- Next.js 13 (app router)
- React + TailwindCSS + RadixUI
- Prisma ORM + Supabase
- Electron (main, preload, BrowserWindow)
- Chart.js / Recharts
- React-PDF / jsPDF

##### Elements
- Clear labels: e.g., “Next.js API Routes (app/api/prices, checklist, summary)”
- UI → API (HTTP)
- API → Database (SQL / Prisma)
- Electron Main ↔ UI (IPC)
- UI → PDF Export library (client-side)
- Blue for client-side components (React pages & components)
- Green for backend services (Next.js API)
- Orange for data stores (Supabase)
- Purple for desktop shell (Electron)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    subgraph "Clients"
        direction TB
        subgraph "Web Client" 
            direction TB
            W_layout["layout.tsx"]:::client
            W_page["page.tsx"]:::client
            W_cp["checklist/page.tsx"]:::client
            W_cd["checklist/checklist-detail.tsx"]:::client
            W_cf["checklist/checklist-form.tsx"]:::client
            W_ct["checklist/checklist-table.tsx"]:::client
        end
        subgraph "Electron Desktop Client" 
            direction TB
            E_main["main.js"]:::desktop
            E_preload["preload.js"]:::desktop
            E_UI["Embedded Next.js UI"]:::client
        end
    end

    %% Backend/API
    subgraph "Backend / API" 
        direction TB
        API_prices["Prices API\n(app/api/prices)"]:::backend
        API_check["Checklist API\n(app/api/checklist)"]:::backend
        API_items["Checklist Items API\n(app/api/checklist/items)"]:::backend
        API_sheets["Checklist Sheets API\n(app/api/checklist/sheets)"]:::backend
        API_summary["Summary API\n(app/api/summary/all)"]:::backend
    end

    %% Database
    Database["Supabase (PostgreSQL)"]:::db

    %% Shared Code / Utilities
    subgraph "Shared Code / Utilities"
        direction TB
        DB_conn["database-electron.ts"]:::shared
        Utils["utils.ts"]:::shared
        subgraph "PDF / Export Service"
            direction TB
            PDF_doc["pdf-document.tsx"]:::pdf
            Export_lib["export.ts"]:::pdf
        end
        subgraph "UI Components"
            direction TB
            C_dashboard["dashboard.tsx"]:::shared
            C_chart["price-chart.tsx"]:::shared
            C_table["recent-prices-table.tsx"]:::shared
            C_form["price-form.tsx"]:::shared
            C_msum["monthly-summary.tsx"]:::shared
            C_dsum["daily-summary.tsx"]:::shared
            C_export["export-options.tsx"]:::shared
        end
        subgraph "UI Library"
            direction TB
            UI_lib["components/ui/*"]:::shared
        end
        subgraph "Hooks"
            direction TB
            H_mobile["use-mobile.tsx"]:::shared
            H_toast["use-toast.ts"]:::shared
        end
        subgraph "Types"
            direction TB
            T_elec["electron.d.ts"]:::shared
            T_index["index.ts"]:::shared
        end
    end

    %% Interactions
    W_layout -->|GET /api/prices| API_prices
    W_page -->|GET /api/summary| API_summary
    W_cp -->|CRUD /api/checklist| API_check
    W_cd -->|CRUD /api/checklist/items| API_items
    W_cf -->|CRUD /api/checklist/sheets| API_sheets
    W_ct -->|GET /api/checklist| API_check

    E_UI -->|HTTP /api/*| API_prices
    E_UI -->|HTTP /api/*| API_check

    E_main <--> E_preload
    E_preload --> E_UI

    API_prices -->|Prisma SQL| Database
    API_check -->|Prisma SQL| Database
    API_items -->|Prisma SQL| Database
    API_sheets -->|Prisma SQL| Database
    API_summary -->|Prisma SQL| Database

    W_layout -->|generate PDF| PDF_doc
    E_UI -->|generate PDF| PDF_doc

    %% Click Events
    click W_layout "https://github.com/naiplawan/pos-retail-shop/blob/master/app/layout.tsx"
    click W_page "https://github.com/naiplawan/pos-retail-shop/blob/master/app/page.tsx"
    click W_cp "https://github.com/naiplawan/pos-retail-shop/blob/master/app/checklist/page.tsx"
    click W_cd "https://github.com/naiplawan/pos-retail-shop/blob/master/app/checklist/checklist-detail.tsx"
    click W_cf "https://github.com/naiplawan/pos-retail-shop/blob/master/app/checklist/checklist-form.tsx"
    click W_ct "https://github.com/naiplawan/pos-retail-shop/blob/master/app/checklist/checklist-table.tsx"
    click E_main "https://github.com/naiplawan/pos-retail-shop/blob/master/electron/main.js"
    click E_preload "https://github.com/naiplawan/pos-retail-shop/blob/master/electron/preload.js"
    click API_prices "https://github.com/naiplawan/pos-retail-shop/blob/master/app/api/prices/route.ts"
    click API_check "https://github.com/naiplawan/pos-retail-shop/blob/master/app/api/checklist/route.ts"
    click API_items "https://github.com/naiplawan/pos-retail-shop/blob/master/app/api/checklist/items/route.ts"
    click API_sheets "https://github.com/naiplawan/pos-retail-shop/blob/master/app/api/checklist/sheets/route.ts"
    click API_summary "https://github.com/naiplawan/pos-retail-shop/blob/master/app/api/summary/all/route.ts"
    click DB_conn "https://github.com/naiplawan/pos-retail-shop/blob/master/lib/database-electron.ts"
    click PDF_doc "https://github.com/naiplawan/pos-retail-shop/blob/master/lib/pdf-document.tsx"
    click Export_lib "https://github.com/naiplawan/pos-retail-shop/blob/master/lib/export.ts"
    click Utils "https://github.com/naiplawan/pos-retail-shop/blob/master/lib/utils.ts"
    click C_dashboard "https://github.com/naiplawan/pos-retail-shop/blob/master/components/dashboard.tsx"
    click C_chart "https://github.com/naiplawan/pos-retail-shop/blob/master/components/price-chart.tsx"
    click C_table "https://github.com/naiplawan/pos-retail-shop/blob/master/components/recent-prices-table.tsx"
    click C_form "https://github.com/naiplawan/pos-retail-shop/blob/master/components/price-form.tsx"
    click C_msum "https://github.com/naiplawan/pos-retail-shop/blob/master/components/monthly-summary.tsx"
    click C_dsum "https://github.com/naiplawan/pos-retail-shop/blob/master/components/daily-summary.tsx"
    click C_export "https://github.com/naiplawan/pos-retail-shop/blob/master/components/export-options.tsx"
    click UI_lib "https://github.com/naiplawan/pos-retail-shop/tree/master/components/ui/"
    click H_mobile "https://github.com/naiplawan/pos-retail-shop/blob/master/hooks/use-mobile.tsx"
    click H_toast "https://github.com/naiplawan/pos-retail-shop/blob/master/hooks/use-toast.ts"
    click T_elec "https://github.com/naiplawan/pos-retail-shop/blob/master/types/electron.d.ts"
    click T_index "https://github.com/naiplawan/pos-retail-shop/blob/master/types/index.ts"

    %% Styles
    classDef client fill:#D5E8FF,stroke:#6C8EBF
    classDef backend fill:#D0E8D0,stroke:#82B366
    classDef db fill:#F8CECC,stroke:#B85450
    classDef desktop fill:#E1D5E7,stroke:#9673A6
    classDef shared fill:#FFF2CC,stroke:#D6B656
    classDef pdf fill:#FFE6CC,stroke:#DFA05F
```
