# mahingarodin/multi-tenant-pos-api architecture

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

- Interactive diagram: https://gitdiagram.com/mahingarodin/multi-tenant-pos-api
- Repository: https://github.com/mahingarodin/multi-tenant-pos-api

## Overview

1. **Overall shape**
This is a single Spring Boot backend for a multi-tenant POS SaaS, organized as a classic layered monolith: HTTP controllers at the edge, service/implementation classes for business logic, repositories for persistence, and shared model/DTO/mapping packages in between.

2. **Runtime and packaging**
The application starts from `MultiTenantSaaSPosSystemApplication` and targets Java 21. It is built with Maven, runs as a standard Spring Boot service, and is packaged for both local Docker execution and Kubernetes deployment.

3. **API surface**
The controller layer is broad and domain-oriented: `Auth`, `User`, `Store`, `Branch`, `Category`, `Product`, `Inventory`, `Customer`, `Employee`, `Order`, `Refund`, `ShiftReport`, and `Cache`. This suggests the system is exposed as a REST API with separate entry points for account management, retail operations, stock movement, and reporting.

4. **Security boundary**
Authentication is stateless and JWT-based. `SecurityConfig`, `JwtProvider`, `JwtValidator`, and `JwtConstant` define the auth boundary, while `AuthController`/`AuthServiceImpl` handle login and token issuance. `CustomUserImpl`, role/status enums, and user-domain classes indicate Spring Security is used for role-based access control.

5. **Business-logic layer**
Each major domain has a service interface plus an `Impl` class: stores, branches, products, categories, inventory, customers, orders, refunds, shift reports, users, and employees. This is where workflow rules likely live, such as stock updates after orders, shift aggregation, and tenant/store scoping.

6. **Persistence model**
Persistence is split into JPA entities under `models`, Spring Data repositories under `repositories`, and mapper classes under `mappers`. The entity set centers on retail concepts like `Store`, `Branch`, `Product`, `Inventory`, `Order`, `OrderItem`, `Refund`, `Customer`, `ShiftReport`, and `User`, with PostgreSQL as the backing database.

7. **DTO and response boundary**
The API does not appear to expose entities directly. Instead, request/response objects live in `payloads/dtos` and `payloads/response`, which creates a clear boundary between external API contracts and internal persistence models. That’s important for an architecture diagram because it separates transport shape from database shape.

8. **Multi-tenant/domain scoping**
The repository frames itself as multi-tenant, but the visible code suggests tenancy is expressed through the domain model and access control rather than separate per-tenant services. `Store` and `Branch` are the key structural units, with user/role boundaries and likely tenant-aware queries in the service/repository layer.

9. **Caching and performance**
Redis is a first-class supporting subsystem. `RedisConfig` and `CacheController` indicate caching is used for frequently accessed data such as catalog, branch, or store-related lookups, reducing load on PostgreSQL and improving latency.

10. **External integration and ops**
The README describes payment, email, and API-doc integrations as part of the product story, while the codebase concretely includes Swagger/OpenAPI config and Spring Mail in the stack. Operationally, the repo includes Docker, Kubernetes manifests for the app plus PostgreSQL and Redis, and a GitHub Actions deploy workflow, so deployment is treated as a cloud-native concern.

11. **Schema and initialization**
There is a SQL seed/schema file (`pos_db.sql`) and a Flyway migration under `src/main/resources/db/migrations`, plus a `DataInitializer` config class. This means the app expects database schema management and startup data bootstrapping to be part of the runtime setup.

12. **Testing footprint**
Tests are present but focused: there are application smoke tests, Redis serialization tests, and controller tests for auth and branch flows. That suggests the most critical verified boundaries are bootstrapping, cache behavior, and core API endpoints.

Main entry points: [`src/main/java/com/msp/repositories/OrderRepository.java`](https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/repositories/OrderRepository.java) (Repositories), [`src/main/java/com/msp/controllers/ProductController.java`](https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/controllers/ProductController.java) (Catalog API), [`src/main/java/com/msp/MultiTenantSaaSPosSystemApplication.java`](https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/MultiTenantSaaSPosSystemApplication.java) (App), [`k8s/deployment.yaml`](https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/k8s/deployment.yaml) (Deploy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_runtime["Runtime"]
  node_app(("App<br/>spring boot entrypoint"))
  node_security["Security"]
  node_jwt["JWT<br/>token support<br/>[JwtProvider.java]"]
  node_openapi["API Docs<br/>openapi config<br/>[OpenApiConfig.java]"]
end

subgraph group_group_api["API"]
  node_authctl["Auth API<br/>rest controller"]
  node_catalog_api["Catalog API<br/>rest controllers"]
  node_cache_api["Cache API<br/>rest controller"]
end

subgraph group_group_domain["Domain"]
  node_authsvc["Auth Service<br/>service impl"]
  node_usersvc["User Service<br/>service impl"]
  node_storesvc["Store Service<br/>service impl"]
  node_inventorysvc["Inventory Service<br/>service impl"]
  node_ordersvc["Order Service<br/>service impl"]
  node_refundsvc["Refund Service<br/>service impl"]
  node_mapper["Mappers<br/>dto/entity mapping<br/>[OrderMapper.java]"]
end

subgraph group_group_data["Data"]
  node_entities[("Entities<br/>jpa models<br/>[Order.java]")]
  node_repos["Repositories<br/>spring data"]
end

subgraph group_group_ops["Ops"]
  node_init["Init Data<br/>bootstrap config"]
  node_redis[("Redis<br/>cache config<br/>[RedisConfig.java]")]
  node_flyway["Migrations<br/>schema migration"]
  node_k8s["Deploy<br/>kubernetes manifests<br/>[deployment.yaml]"]
end

node_app -->|"configures"| node_security
node_app -->|"starts API"| node_authctl
node_app -->|"loads"| node_init
node_app -->|"documents"| node_openapi
node_security -->|"uses"| node_jwt
node_authctl -->|"calls"| node_authsvc
node_catalog_api -->|"calls"| node_storesvc
node_catalog_api -->|"calls"| node_inventorysvc
node_catalog_api -->|"calls"| node_ordersvc
node_catalog_api -->|"calls"| node_refundsvc
node_catalog_api -->|"calls"| node_usersvc
node_authsvc -->|"persists via"| node_repos
node_usersvc -->|"persists via"| node_repos
node_storesvc -->|"persists via"| node_repos
node_inventorysvc -->|"persists via"| node_repos
node_ordersvc -->|"persists via"| node_repos
node_refundsvc -->|"persists via"| node_repos
node_mapper -->|"maps to"| node_entities
node_repos -->|"stores"| node_entities
node_redis -->|"supports"| node_cache_api
node_flyway -->|"evolves"| node_repos
node_k8s -->|"deploys"| node_app
node_k8s -->|"deploys"| node_redis
node_k8s -->|"depends on"| node_repos

click node_app "https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/MultiTenantSaaSPosSystemApplication.java"
click node_security "https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/configs/SecurityConfig.java"
click node_jwt "https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/configs/JwtProvider.java"
click node_authctl "https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/controllers/AuthController.java"
click node_catalog_api "https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/controllers/ProductController.java"
click node_cache_api "https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/controllers/CacheController.java"
click node_authsvc "https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/impls/AuthServiceImpl.java"
click node_usersvc "https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/impls/UserServiceImpl.java"
click node_storesvc "https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/impls/StoreServiceImpl.java"
click node_inventorysvc "https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/impls/InventoryServiceImpl.java"
click node_ordersvc "https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/impls/OrderServiceImpl.java"
click node_refundsvc "https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/impls/RefundServiceImpl.java"
click node_mapper "https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/mappers/OrderMapper.java"
click node_entities "https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/models/Order.java"
click node_repos "https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/repositories/OrderRepository.java"
click node_init "https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/configs/DataInitializer.java"
click node_redis "https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/configs/RedisConfig.java"
click node_flyway "https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/resources/db/migrations/V1__add_discharged_at_to_users.sql"
click node_k8s "https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/k8s/deployment.yaml"
click node_openapi "https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/configs/OpenApiConfig.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_security,node_jwt,node_openapi toneBlue
class node_authctl,node_catalog_api,node_cache_api toneAmber
class node_authsvc,node_usersvc,node_storesvc,node_inventorysvc,node_ordersvc,node_refundsvc,node_mapper toneMint
class node_entities,node_repos toneRose
class node_init,node_redis,node_flyway,node_k8s toneIndigo
```

## Components

### Runtime

Application bootstrap and security/runtime configuration

- [App](https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/MultiTenantSaaSPosSystemApplication.java): spring boot entrypoint · Main application bootstrap for the POS backend · `src/main/java/com/msp/MultiTenantSaaSPosSystemApplication.java`
- [Security](https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/configs/SecurityConfig.java): jwt security · HTTP security boundary and stateless JWT auth setup · `src/main/java/com/msp/configs/SecurityConfig.java`
- [JWT](https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/configs/JwtProvider.java): token support · JWT token creation, validation, and constants · `src/main/java/com/msp/configs/JwtProvider.java`
- [API Docs](https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/configs/OpenApiConfig.java): openapi config · Swagger/OpenAPI documentation setup · `src/main/java/com/msp/configs/OpenApiConfig.java`

### API

REST entry points and response boundary

- [Auth API](https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/controllers/AuthController.java): rest controller · Login and token issuance endpoints · `src/main/java/com/msp/controllers/AuthController.java`
- [Catalog API](https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/controllers/ProductController.java): rest controllers · Store, branch, category, product, inventory, customer, employee, order, refund, and report endpoints · `src/main/java/com/msp/controllers/ProductController.java`
- [Cache API](https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/controllers/CacheController.java): rest controller · Cache-oriented endpoint surface · `src/main/java/com/msp/controllers/CacheController.java`

### Domain

Business services and mappers

- [Auth Service](https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/impls/AuthServiceImpl.java): service impl · Authentication workflow and token response creation · `src/main/java/com/msp/impls/AuthServiceImpl.java`
- [User Service](https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/impls/UserServiceImpl.java): service impl · User lifecycle and account management logic · `src/main/java/com/msp/impls/UserServiceImpl.java`
- [Store Service](https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/impls/StoreServiceImpl.java): service impl · Store and tenant-scoping business rules · `src/main/java/com/msp/impls/StoreServiceImpl.java`
- [Inventory Service](https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/impls/InventoryServiceImpl.java): service impl · Stock movement and availability logic · `src/main/java/com/msp/impls/InventoryServiceImpl.java`
- [Order Service](https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/impls/OrderServiceImpl.java): service impl · Order creation, payment, and fulfillment workflows · `src/main/java/com/msp/impls/OrderServiceImpl.java`
- [Refund Service](https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/impls/RefundServiceImpl.java): service impl · Refund handling and order reversal rules · `src/main/java/com/msp/impls/RefundServiceImpl.java`
- [Mappers](https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/mappers/OrderMapper.java): dto/entity mapping · Translation layer between API DTOs and persistence models · `src/main/java/com/msp/mappers/OrderMapper.java`

### Data

Entities, repositories, and database setup

- [Entities](https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/models/Order.java): jpa models · Core persistence model for stores, users, products, orders, and reports · `src/main/java/com/msp/models/Order.java`
- [Repositories](https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/repositories/OrderRepository.java): spring data · Database access for entity aggregates · `src/main/java/com/msp/repositories/OrderRepository.java`

### Ops

Cache, schema, and deployment concerns

- [Init Data](https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/configs/DataInitializer.java): bootstrap config · Startup seeding and initialization hooks · `src/main/java/com/msp/configs/DataInitializer.java`
- [Redis](https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/java/com/msp/configs/RedisConfig.java): cache config · Redis configuration and cached lookup support · `src/main/java/com/msp/configs/RedisConfig.java`
- [Migrations](https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/src/main/resources/db/migrations/V1__add_discharged_at_to_users.sql): schema migration · Database migration scripts and schema evolution · `src/main/resources/db/migrations/V1__add_discharged_at_to_users.sql`
- [Deploy](https://github.com/mahingarodin/multi-tenant-pos-api/blob/main/k8s/deployment.yaml): kubernetes manifests · Container, PostgreSQL, Redis, service, and ingress deployment manifests · `k8s/deployment.yaml`

## Connections

- App → Security: configures · Bootstraps application security and authentication
- App → Auth API: starts API · Runs the REST application surface
- App → Init Data: loads · Initializes startup data and bootstrap behavior
- App → API Docs: documents · Publishes API documentation setup
- Security → JWT: uses · Delegates auth behavior to JWT provider and validator
- Auth API → Auth Service: calls · Routes login requests into authentication workflow
- Catalog API → Store Service: calls · Store and tenant operations
- Catalog API → Inventory Service: calls · Stock and availability operations
- Catalog API → Order Service: calls · Order workflow endpoints
- Catalog API → Refund Service: calls · Refund and reversal endpoints
- Catalog API → User Service: calls · User and staff management endpoints
- Auth Service → Repositories: persists via · Reads and writes account data
- User Service → Repositories: persists via · Uses repositories for user data access
- Store Service → Repositories: persists via · Uses repositories for store-scoped data access
- Inventory Service → Repositories: persists via · Reads and updates inventory state
- Order Service → Repositories: persists via · Stores orders and order items
- Refund Service → Repositories: persists via · Stores refund records
- Mappers → Entities: maps to · Converts API payloads into domain models
- Repositories → Entities: stores · Repository layer manages JPA entities
- Redis → Cache API: supports · Exposes cache-backed operations
- Migrations → Repositories: evolves · Keeps repository schema aligned with migrations
- Deploy → App: deploys · Deploys the backend runtime and supporting services
- Deploy → Redis: deploys · Includes Redis runtime in cluster manifests
- Deploy → Repositories: depends on · Application persistence layer backed by PostgreSQL
