How mahingarodin/multi-tenant-pos-api works
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: OrderRepository.java Repositories · ProductController.java Catalog API · MultiTenantSaaSPosSystemApplication.java App · deployment.yaml Deploy
Components 20
Runtime
Application bootstrap and security/runtime configuration
- App · Main application bootstrap for the POS backend
src/main/java/com/msp/MultiTenantSaaSPosSystemApplication.java - Security · HTTP security boundary and stateless JWT auth setup
src/main/java/com/msp/configs/SecurityConfig.java - JWT · JWT token creation, validation, and constants
src/main/java/com/msp/configs/JwtProvider.java - API Docs · Swagger/OpenAPI documentation setup
src/main/java/com/msp/configs/OpenApiConfig.java
API
REST entry points and response boundary
- Auth API · Login and token issuance endpoints
src/main/java/com/msp/controllers/AuthController.java - Catalog API · Store, branch, category, product, inventory, customer, employee, order, refund, and report endpoints
src/main/java/com/msp/controllers/ProductController.java - Cache API · Cache-oriented endpoint surface
src/main/java/com/msp/controllers/CacheController.java
Domain
Business services and mappers
- Auth Service · Authentication workflow and token response creation
src/main/java/com/msp/impls/AuthServiceImpl.java - User Service · User lifecycle and account management logic
src/main/java/com/msp/impls/UserServiceImpl.java - Store Service · Store and tenant-scoping business rules
src/main/java/com/msp/impls/StoreServiceImpl.java - Inventory Service · Stock movement and availability logic
src/main/java/com/msp/impls/InventoryServiceImpl.java - Order Service · Order creation, payment, and fulfillment workflows
src/main/java/com/msp/impls/OrderServiceImpl.java - Refund Service · Refund handling and order reversal rules
src/main/java/com/msp/impls/RefundServiceImpl.java - Mappers · Translation layer between API DTOs and persistence models
src/main/java/com/msp/mappers/OrderMapper.java
Data
Entities, repositories, and database setup
- Entities · Core persistence model for stores, users, products, orders, and reports
src/main/java/com/msp/models/Order.java - Repositories · Database access for entity aggregates
src/main/java/com/msp/repositories/OrderRepository.java
Ops
Cache, schema, and deployment concerns
- Init Data · Startup seeding and initialization hooks
src/main/java/com/msp/configs/DataInitializer.java - Redis · Redis configuration and cached lookup support
src/main/java/com/msp/configs/RedisConfig.java - Migrations · Database migration scripts and schema evolution
src/main/resources/db/migrations/V1__add_discharged_at_to_users.sql - Deploy · Container, PostgreSQL, Redis, service, and ingress deployment manifests
k8s/deployment.yaml
Connections 24
- 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