# minsoeaung/nexus-pos architecture

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

- Interactive diagram: https://gitdiagram.com/minsoeaung/nexus-pos
- Repository: https://github.com/minsoeaung/nexus-pos

## Overview

##### Project Type and Purpose
- Nexus POS is a full-stack, monolithic Point-of-Sale system.
- Frontend: ReactJS SPA (Ant Design, React Query, React Router).
- Backend: ASP.NET Core 8.0 Web API with Entity Framework Core and Microsoft Identity.
- Database: PostgreSQL.
- External service: SMTP (Gmail) for email.

##### Top-Level Components
a. Client/User Interface Container
- Browser running React app (served via `npm run dev` or Nginx in Docker).
b. API Server Container
- ASP.NET Core Web API (Controllers → Services → EF Core Data Access).
c. Database Container
- PostgreSQL instance (connection string configured via `appsettings.json` or user secrets).
d. External Email Service
- SMTP endpoint (Gmail) for password resets, email confirmations.
e. (Optional) Reverse Proxy / Load Balancer
- Nginx (configured in `Frontend/nginx.conf`) if deployed via Docker.

##### Relationships and Data Flows
- User → React UI: navigates pages and invokes actions.
- React UI → Web API: HTTP(S) calls via `apiClient.ts` (authenticated with JWT tokens stored in localStorage).
- Web API → PostgreSQL: CRUD operations through EF Core’s `StoreContext`.
- Web API → SMTP Server: outgoing email via `EmailSender` service.
- Database migrations and seeders run on startup (`StoreContext`, `Seeders`).
- Identity flows (login, refresh tokens, password resets) via Microsoft Identity endpoints.

##### Important Architectural Patterns & Layers
- Layered Monolith:
- Presentation Layer (API Controllers)
- Business Layer (Services, Middlewares, Request Helpers)
- Data Layer (EF Core Entities, Migrations, Context)
- DTO/Mapping Layer (Mapster mappings)
- JWT-based stateless authentication with refresh tokens.
- Middleware pipeline (e.g., `SuspendCheckMiddleware`, global error handling).
- React Query for client-side data caching and synchronization.

##### Showing Dependencies & Data Flow
- If using Docker Compose: group Frontend, Backend, DB under one “Docker Network.”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External
    User["User"]:::external
    SMTP["SMTP (Gmail)"]:::external

    %% Trusted Zone / Docker Network
    subgraph "Docker Network"
        direction TB
        %% Frontend
        subgraph "Frontend (React SPA)"
            direction TB
            FrontendContainer["React SPA"]:::frontend
            Entry["Main Entry (main.tsx / RootLayout.tsx)"]:::frontend
            Router["React Router (router.tsx)"]:::frontend
            APIClient["API Client (apiClient.ts)"]:::frontend
            AuthCtx["AuthContext & useLocalStorage"]:::frontend
            UIComp["UI Components"]:::frontend
            Pages["Page Views"]:::frontend
            Configs["Env & Build Configs & nginx.conf"]:::frontend
        end

        %% Backend
        subgraph "Backend (ASP.NET Core API)"
            direction TB
            BackendContainer["ASP.NET Core API"]:::backend
            Program["Program.cs & Backend.csproj"]:::backend
            Controllers["API Controllers"]:::backend
            Services["EmailSender & Business Services"]:::backend
            SMTPConf["MailConfig.cs & appsettings.json"]:::backend
            Middleware["Middlewares & ErrorsController"]:::backend
            DataCtx["StoreContext & Seeders"]:::backend
            Migrations["Migrations"]:::backend
            Entities["Domain Entities"]:::backend
            Dtos["DTOs"]:::backend
            Mappings["Mapster Mappings & Extensions"]:::backend
            ReqHelpers["Request Helpers & Pagination"]:::backend
            IdentityEnt["AppUser & AppRole Entities"]:::backend
        end

        %% Database
        DB["PostgreSQL"]:::database
    end

    %% Connections
    User -->|"1: HTTP(S) Requests"| FrontendContainer
    FrontendContainer -->|"2: REST API Calls (with JWT)"| Program
    Program -->|"3: SQL Queries"| DB
    Program -->|"4: Send Emails (SMTP)"| SMTP

    %% Internal Backend Flow
    Program --> Controllers
    Controllers --> Services
    Services --> DataCtx
    DataCtx --> DB
    Controllers --> Middleware
    Services --> SMTPConf
    DataCtx --> Migrations
    DataCtx --> Entities
    Controllers --> Dtos
    Controllers --> ReqHelpers
    Controllers --> Mappings
    Entities --> IdentityEnt

    %% Click Events - Frontend
    click FrontendContainer "https://github.com/minsoeaung/nexus-pos/tree/master/Frontend/"
    click Entry "https://github.com/minsoeaung/nexus-pos/blob/master/Frontend/src/main.tsx"
    click Entry "https://github.com/minsoeaung/nexus-pos/blob/master/Frontend/src/pages/RootLayout.tsx"
    click Router "https://github.com/minsoeaung/nexus-pos/blob/master/Frontend/src/pages/router.tsx"
    click APIClient "https://github.com/minsoeaung/nexus-pos/blob/master/Frontend/src/api/apiClient.ts"
    click AuthCtx "https://github.com/minsoeaung/nexus-pos/blob/master/Frontend/src/context/AuthContext.tsx"
    click AuthCtx "https://github.com/minsoeaung/nexus-pos/blob/master/Frontend/src/hooks/useLocalStorage.ts"
    click UIComp "https://github.com/minsoeaung/nexus-pos/tree/master/Frontend/src/components/"
    click Pages "https://github.com/minsoeaung/nexus-pos/tree/master/Frontend/src/pages/"
    click Configs "https://github.com/minsoeaung/nexus-pos/blob/master/Frontend/.env.development"
    click Configs "https://github.com/minsoeaung/nexus-pos/blob/master/Frontend/.env.production"
    click Configs "https://github.com/minsoeaung/nexus-pos/blob/master/Frontend/vite.config.ts"
    click Configs "https://github.com/minsoeaung/nexus-pos/blob/master/Frontend/nginx.conf"

    %% Click Events - Backend
    click BackendContainer "https://github.com/minsoeaung/nexus-pos/blob/master/Backend/Program.cs"
    click BackendContainer "https://github.com/minsoeaung/nexus-pos/blob/master/Backend/Backend.csproj"
    click Controllers "https://github.com/minsoeaung/nexus-pos/tree/master/Backend/Controllers/"
    click Services "https://github.com/minsoeaung/nexus-pos/blob/master/Backend/Services/EmailSender.cs"
    click SMTPConf "https://github.com/minsoeaung/nexus-pos/blob/master/Backend/Configs/MailConfig.cs"
    click SMTPConf "https://github.com/minsoeaung/nexus-pos/blob/master/Backend/appsettings.json"
    click Middleware "https://github.com/minsoeaung/nexus-pos/blob/master/Backend/Middlewares/SuspendCheckMiddleware.cs"
    click Middleware "https://github.com/minsoeaung/nexus-pos/blob/master/Backend/Controllers/ErrorsController.cs"
    click DataCtx "https://github.com/minsoeaung/nexus-pos/blob/master/Backend/Data/StoreContext.cs"
    click DataCtx "https://github.com/minsoeaung/nexus-pos/blob/master/Backend/Data/Seeders.cs"
    click Migrations "https://github.com/minsoeaung/nexus-pos/tree/master/Backend/Data/Migrations/"
    click Entities "https://github.com/minsoeaung/nexus-pos/tree/master/Backend/Entities/"
    click Dtos "https://github.com/minsoeaung/nexus-pos/tree/master/Backend/Dtos/"
    click Mappings "https://github.com/minsoeaung/nexus-pos/tree/master/Backend/Mappings/"
    click Mappings "https://github.com/minsoeaung/nexus-pos/blob/master/Backend/Extensions/MapsterExtensions.cs"
    click ReqHelpers "https://github.com/minsoeaung/nexus-pos/tree/master/Backend/RequestHelpers/"
    click IdentityEnt "https://github.com/minsoeaung/nexus-pos/blob/master/Backend/Entities/AppUser.cs"
    click IdentityEnt "https://github.com/minsoeaung/nexus-pos/blob/master/Backend/Entities/AppRole.cs"

    %% Deployment & CI/CD
    subgraph "Deployment & CI/CD"
        dockerCompose["docker-compose.yaml"]:::deployment
        DockerfileFE["Frontend/Dockerfile"]:::deployment
        DockerfileBE["Backend/Dockerfile"]:::deployment
        Workflow[".github/workflows/deploy.yml"]:::deployment
        Solution["NexusPOS.sln"]:::deployment
        Docs["README.md & Screenshots"]:::deployment
    end

    %% Click Events - Deployment
    click dockerCompose "https://github.com/minsoeaung/nexus-pos/blob/master/docker-compose.yaml"
    click DockerfileFE "https://github.com/minsoeaung/nexus-pos/tree/master/Frontend/Dockerfile"
    click DockerfileBE "https://github.com/minsoeaung/nexus-pos/tree/master/Backend/Dockerfile"
    click Workflow "https://github.com/minsoeaung/nexus-pos/blob/master/.github/workflows/deploy.yml"
    click Solution "https://github.com/minsoeaung/nexus-pos/blob/master/NexusPOS.sln"
    click Docs "https://github.com/minsoeaung/nexus-pos/blob/master/README.md"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#66b0ff,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#82c784,stroke-width:2px;
    classDef database fill:#ffe5b4,stroke:#ffb74d,stroke-width:2px,stroke-dasharray: 5 5;
    classDef external fill:#e2e3e5,stroke:#bcbfc4,stroke-width:2px;
    classDef deployment fill:#f8d7da,stroke:#f5c6cb,stroke-width:2px;
```
