# alexsantosdev/open-pos architecture

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

- Interactive diagram: https://gitdiagram.com/alexsantosdev/open-pos
- Repository: https://github.com/alexsantosdev/open-pos

## Overview

##### Project type and purpose
- This is a full-stack Next.js application used to manage and display merchant inventory and sales, integrate subscription billing (Stripe), and handle authentication (NextAuth + Firebase). The frontend and backend coexist in the same codebase via Next.js pages and API routes.

##### File structure
- Top-level:
- next.config.js, package.json, tsconfig.json → build/config
- src/
– components/ → reusable React UI components (Alert, Modal, Table, etc.)
– hooks/ → custom React hooks (useTable)
– pages/ → Next.js pages (UI) + nested API routes (backend)
- pages/index.tsx, pages/[param].tsx → public-facing pages
- pages/admin/... → merchant dashboard (inventory, sales)
- pages/api/ → serverless functions (auth, subscribe, webhooks)
– services/ → wrappers/clients for external systems (api.ts, firebase.ts, stripe.js/ts)
– styles/, utils/ → global styles and utility functions
- Presence of `.scss` modules everywhere indicates CSS-module styling per component/page.
- API routes under `src/pages/api` represent the backend surface.

##### README for additional insights
- Purpose: development server, hot-reload, API route mapping.

a. Main Components
- Client (Browser)
- Next.js Server (Vercel or Node)
- Pages (SSR/SSG/CSR entry points)
- API Routes (serverless functions)
- Services Layer
- Firebase (Auth & Database)
- Stripe (Billing & Webhooks)
- Data Stores
- Firestore / Realtime DB (implied by firebase.ts)
- Stripe’s backend
- External Identity Provider (NextAuth providers)

b. Relationships & Interactions
1. Client → Next.js Pages: HTTP(S) requests for UI (SSR or static).
2. Pages render React components; use `services/api.ts` for client-side data fetching (CSR).
3. Client calls `/api/*` endpoints for protected actions:
- `/api/auth/[...nextauth]` → NextAuth handshake → Firebase Auth
- `/api/subscribe` → Stripe subscription creation
- `/api/webhooks` → Stripe webhook events → manageSubscription
4. API Routes → Services → External Systems:
- Firebase SDK in `services/firebase.ts` (CRUD merchant data)
- Stripe SDK in `services/stripe.ts` (charge, subscription)
5. External Systems send events (e.g., Stripe webhook) back to API Routes.

c. Architectural Patterns & Design Principles
- Separation of concerns:
- UI (components/)
- State & side-effects (hooks/, services/)
- Data/API surface (pages/api/)
- Server-Side Rendering (SSR) and Client-Side Rendering (CSR) via Next.js.
- Serverless functions as micro-backends (API routes).
- Modular SCSS for scoped styling.

d. Key Technologies & Frameworks
- Next.js (SSR/SSG/CSR + API routes)
- React + TypeScript
- NextAuth.js for authentication
- Firebase SDK (Authentication + Firestore)
- Stripe SDK (Payments & Webhooks)
- SCSS Modules

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Layer
    subgraph "Browser (Client)" 
        direction TB
        Client["Client Browser"]:::ui
        Client -->|"GET /"| HomePage
        Client -->|"GET /[param]"| DynamicPage
        Client -->|"GET /admin/[merchantid]"| AdminWrapper
        Client -->|"GET /admin/inventory/[merchantid]"| InventoryPage
        Client -->|"GET /admin/sale/[merchantid]"| SalesPage
        HomePage -->|renders| ProductTable
        DynamicPage -->|renders| PageComponent
    end

    %% Next.js Server Layer
    subgraph "Next.js Server" 
        direction TB
        PagesGroup["Pages"]:::pages
        ApiGroup["API Routes"]:::api
        PagesGroup -->|SSR/CSR| _App
        PagesGroup -->|Document Custom| _Document
        PagesGroup --> HomePage
        PagesGroup --> DynamicPage
        PagesGroup --> AdminWrapper
        PagesGroup --> InventoryPage
        PagesGroup --> SalesPage

        ApiGroup --> AuthApi
        ApiGroup --> SubscribeApi
        ApiGroup --> WebhooksApi
        ApiGroup --> ManageSub
    end

    %% Services Layer
    subgraph "Services Layer" 
        direction TB
        ApiWrapper["services/api.ts"]:::service
        FirebaseWrapper["services/firebase.ts"]:::service
        StripeJS["services/stripe-js.ts"]:::service
        StripeServer["services/stripe.ts"]:::service
    end

    %% External Systems & Data Stores
    subgraph "External Systems" 
        direction TB
        FirebaseAuth["Firebase Auth"]:::external
        FirestoreDB["Firestore/Realtime DB"]:::external
        StripeService["Stripe API"]:::external
    end

    %% Connections
    HomePage -->|"use services/api"| ApiWrapper
    DynamicPage -->|"use services/api"| ApiWrapper
    AdminWrapper -->|"use services/api"| ApiWrapper
    InventoryPage -->|"use services/api"| ApiWrapper
    SalesPage -->|"use services/api"| ApiWrapper

    AuthApi -->|"Firebase SDK calls"| FirebaseWrapper
    SubscribeApi -->|"Stripe SDK calls"| StripeServer
    WebhooksApi -->|"manages events"| ManageSub
    ManageSub -->|"uses SDK"| StripeServer
    ManageSub -->|"updates"| FirebaseWrapper

    FirebaseWrapper -->|"CRUD data"| FirestoreDB
    StripeServer -->|"HTTP calls"| StripeService
    StripeJS -->|"client embed"| StripeService

    StripeService -.->|"webhook event"| WebhooksApi

    Client -->|"NextAuth handshake"| AuthApi

    %% Click Events
    click ProductTable "https://github.com/alexsantosdev/open-pos/tree/main/src/components/"
    click PageComponent "https://github.com/alexsantosdev/open-pos/tree/main/src/components/"
    click HomePage "https://github.com/alexsantosdev/open-pos/blob/main/src/pages/index.tsx"
    click DynamicPage "https://github.com/alexsantosdev/open-pos/blob/main/src/pages/[param].tsx"
    click AdminWrapper "https://github.com/alexsantosdev/open-pos/blob/main/src/pages/admin/[merchantid].tsx"
    click InventoryPage "https://github.com/alexsantosdev/open-pos/blob/main/src/pages/admin/inventory/[merchantid].tsx"
    click SalesPage "https://github.com/alexsantosdev/open-pos/blob/main/src/pages/admin/sale/[merchantid].tsx"
    click _App "https://github.com/alexsantosdev/open-pos/blob/main/src/pages/_app.tsx"
    click _Document "https://github.com/alexsantosdev/open-pos/blob/main/src/pages/_document.tsx"
    click AuthApi "https://github.com/alexsantosdev/open-pos/blob/main/src/pages/api/auth/[...nextauth].tsx"
    click SubscribeApi "https://github.com/alexsantosdev/open-pos/blob/main/src/pages/api/subscribe.ts"
    click WebhooksApi "https://github.com/alexsantosdev/open-pos/blob/main/src/pages/api/webhooks.ts"
    click ManageSub "https://github.com/alexsantosdev/open-pos/blob/main/src/pages/api/_lib/manageSubscription.ts"
    click ApiWrapper "https://github.com/alexsantosdev/open-pos/blob/main/src/services/api.ts"
    click FirebaseWrapper "https://github.com/alexsantosdev/open-pos/blob/main/src/services/firebase.ts"
    click StripeJS "https://github.com/alexsantosdev/open-pos/blob/main/src/services/stripe-js.ts"
    click StripeServer "https://github.com/alexsantosdev/open-pos/blob/main/src/services/stripe.ts"
    click InventoryPageStyles "https://github.com/alexsantosdev/open-pos/blob/main/src/pages/admin/inventory/inventory.module.scss"
    click SalesPageStyles "https://github.com/alexsantosdev/open-pos/blob/main/src/pages/admin/sale/sale.module.scss"
    click HomePageStyles "https://github.com/alexsantosdev/open-pos/blob/main/src/pages/home.module.scss"
    click Hooks "https://github.com/alexsantosdev/open-pos/blob/main/src/hooks/useTable.ts"
    click GlobalStyles "https://github.com/alexsantosdev/open-pos/blob/main/src/styles/global.scss"

    %% Styles
    classDef ui fill:#D6EAF8,stroke:#2980B9
    classDef pages fill:#AED6F1,stroke:#2980B9
    classDef api fill:#A9DFBF,stroke:#239B56
    classDef service fill:#F9E79F,stroke:#B7950B
    classDef external fill:#F5B7B1,stroke:#C0392B
```
