# l4nci/doprava-kalkulacka architecture

> Architecture diagram of the GitHub repository l4nci/doprava-kalkulacka, 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/l4nci/doprava-kalkulacka
- Repository: https://github.com/l4nci/doprava-kalkulacka

## Overview

##### Project type and purpose
- This is a full-stack web application (“Doprava Kalkulačka 3.0”) for calculating optimal shipment costs (packages and pallets), supporting real-time pricing, multi-currency and multi-country, and providing an admin interface.
- The README specifies React + Vite for the frontend, Supabase for backend/auth and Postgres, TailwindCSS for styling.

##### File structure
- Top-level:
- netlify/ + netlify/functions/audit-log.js → custom serverless function(s) deployed on Netlify
- server.js + src/server/** → an Express-style local or secondary API with audit route
- supabase/…sql → DB schema and migration scripts for Supabase
- public/, index.html, vite.config.js → static assets and Vite config
- src/ contains the React app:
- src/main.jsx, src/App.jsx → entry points
- src/components/ → UI components (Login, Admin, Products, AuditLog, etc.)
- src/contexts/AuthContext.jsx → global auth state (Supabase Auth)
- src/lib/supabaseClient.js & src/supabaseClient.js → Supabase JS client wrappers
- src/services/auditService.js → audit-logging abstraction
- src/hooks/, src/utils/ → data fetching & utility functions
- config files: .env(.example/.production), netlify.toml, tailwind.config.js, postcss.config.js, eslint.config.js.

##### Extract architecture hints from README
- Emphasis on:
- Frontend SPA using React + Vite, hosted on Netlify
- Backend powered by Supabase (Auth + Postgres + Realtime) and custom serverless/API logic
- Tailwind for styling

##### Main components
A. Frontend (React SPA)
- Entry: index.html → main.jsx → App.jsx → components
- Styling: TailwindCSS via postcss
- Data access via supabaseClient and custom REST hooks (useProducts, useCurrency, etc.)
B. Hosting/CDN
- Netlify serves static build artifacts and Netlify Functions
C. API Layer
- Netlify Functions (audit-log.js) for audit logging
- Express/API in server.js or src/server routes (e.g., /audit)
D. Database & Auth
- Supabase (Postgres + Auth + Policies + Triggers)
- SQL migration scripts under supabase/

##### Relationships and data flow
1. User’s browser → requests static SPA from Netlify CDN
2. SPA → Supabase Auth API (login, token)
3. SPA → Supabase Database via supabaseClient for products, pricing, notifications
4. SPA → Netlify Function / Express API for audit logging and admin operations
5. Functions/API → Supabase Database (write audit logs, update products/couriers, etc.)
6. Supabase Realtime (optional) pushes price updates back to SPA

##### Architectural patterns & principles
- SPA + API (decoupled frontend/backend)
- Serverless functions for on-demand backend logic
- Centralized DB as source of truth (Supabase)
- Context API for auth state management
- Hooks & services for data access separation
- SQL migration/versioning for database schema

##### Essential details to capture
- All API endpoints (Netlify function vs. Express routes)
- Supabase DB schema origin (SQL scripts folder)
- Build & deploy pipeline (Vite → Netlify build)
- Environment variables (.env vs .env.production)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (React SPA)"
        direction TB
        BROWSER["User Browser"]:::external
        CDN["Netlify CDN"]:::external
        INDEX["index.html"]:::frontend
        MAIN["main.jsx"]:::frontend
        APP["App.jsx"]:::frontend
        COMPONENTS["src/components/"]:::frontend
        AUTHCTX["AuthContext.jsx"]:::frontend
        SB_LIB["src/lib/supabaseClient.js"]:::frontend
        SB_ALT["src/supabaseClient.js"]:::frontend
        AUDIT_SVC["auditService.js"]:::frontend
        HOOKS["src/hooks/"]:::frontend
        UTILS["src/utils/"]:::frontend
    end

    %% Config Layer
    subgraph "Configuration Files"
        direction TB
        TAILWIND["tailwind.config.js"]:::config
        POSTCSS["postcss.config.js"]:::config
        VITE["vite.config.js"]:::config
        NETLIFY_TOML["netlify.toml"]:::config
        ENV[".env(.example/.production)"]:::config
    end

    %% Hosting & Serverless
    subgraph "Hosting & Serverless"
        direction TB
        NETLIFY_FUNC["audit-log.js (Netlify Function)"]:::api
    end

    %% API Layer
    subgraph "Express API"
        direction TB
        SERVERJS["server.js"]:::api
        EXPRESS_BOOT["src/server/index.js"]:::api
        AUDIT_ROUTE["src/server/routes/audit.js"]:::api
    end

    %% Data Layer
    subgraph "Supabase (DB & Auth)"
        direction TB
        SB_SQL["supabase/ (SQL scripts)"]:::db
        SB_AUTH["Supabase Auth API"]:::external
        SB_DB["Supabase Postgres"]:::db
        SB_RT["Supabase Realtime"]:::external
    end

    %% Relationships
    BROWSER -->|"GET SPA"| CDN
    CDN -->|"serves"| INDEX
    INDEX -->|"loads"| MAIN
    MAIN -->|"renders"| APP
    APP -->|"uses UI"| COMPONENTS
    APP -->|"wraps with"| AUTHCTX
    APP -->|"calls"| SB_LIB
    APP -->|"calls"| SB_ALT
    APP -->|"calls"| AUDIT_SVC
    APP -->|"fetches via hooks"| HOOKS
    APP -->|"uses utils"| UTILS

    APP -->|"Auth API"| SB_AUTH
    APP -->|"read/write data"| SB_DB
    SB_DB -->|"push updates"| SB_RT

    APP -->|"POST /audit-log"| NETLIFY_FUNC
    NETLIFY_FUNC -->|"INSERT audit_log"| SB_DB

    APP -->|"admin ops "| SERVERJS
    SERVERJS -->|"bootstrap"| EXPRESS_BOOT
    EXPRESS_BOOT -->|"route /audit"| AUDIT_ROUTE
    AUDIT_ROUTE -->|"INSERT audit_log"| SB_DB

    %% Config references
    CDN --> NETLIFY_TOML
    INDEX --> VITE
    INDEX --> POSTCSS
    INDEX --> TAILWIND
    MAIN --> ENV

    %% Click Events
    click INDEX "https://github.com/l4nci/doprava-kalkulacka/blob/main/index.html"
    click MAIN "https://github.com/l4nci/doprava-kalkulacka/blob/main/src/main.jsx"
    click APP "https://github.com/l4nci/doprava-kalkulacka/blob/main/src/App.jsx"
    click COMPONENTS "https://github.com/l4nci/doprava-kalkulacka/tree/main/src/components/"
    click AUTHCTX "https://github.com/l4nci/doprava-kalkulacka/blob/main/src/contexts/AuthContext.jsx"
    click SB_LIB "https://github.com/l4nci/doprava-kalkulacka/blob/main/src/lib/supabaseClient.js"
    click SB_ALT "https://github.com/l4nci/doprava-kalkulacka/blob/main/src/supabaseClient.js"
    click AUDIT_SVC "https://github.com/l4nci/doprava-kalkulacka/blob/main/src/services/auditService.js"
    click HOOKS "https://github.com/l4nci/doprava-kalkulacka/tree/main/src/hooks/"
    click UTILS "https://github.com/l4nci/doprava-kalkulacka/tree/main/src/utils/"
    click TAILWIND "https://github.com/l4nci/doprava-kalkulacka/blob/main/tailwind.config.js"
    click POSTCSS "https://github.com/l4nci/doprava-kalkulacka/blob/main/postcss.config.js"
    click VITE "https://github.com/l4nci/doprava-kalkulacka/blob/main/vite.config.js"
    click NETLIFY_TOML "https://github.com/l4nci/doprava-kalkulacka/blob/main/netlify.toml"
    click NETLIFY_FUNC "https://github.com/l4nci/doprava-kalkulacka/blob/main/netlify/functions/audit-log.js"
    click SERVERJS "https://github.com/l4nci/doprava-kalkulacka/blob/main/server.js"
    click EXPRESS_BOOT "https://github.com/l4nci/doprava-kalkulacka/blob/main/src/server/index.js"
    click AUDIT_ROUTE "https://github.com/l4nci/doprava-kalkulacka/blob/main/src/server/routes/audit.js"
    click SB_SQL "https://github.com/l4nci/doprava-kalkulacka/tree/main/supabase/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef api fill:#FFE2B2,stroke:#D29922,color:#D29922;
    classDef db fill:#D1F2C8,stroke:#28A745,color:#28A745;
    classDef external fill:#E2E2E2,stroke:#7A7A7A,color:#4A4A4A;
    classDef config fill:#FFF4D6,stroke:#C9A227,color:#C9A227;
```
