Skip to content

codebase_analysis.md

Latest commit

 

History

History
61 lines (46 loc) · 5.27 KB

codebase_analysis.md

File metadata and controls

61 lines (46 loc) · 5.27 KB
Raw

StoreProject Codebase Analysis

1. Executive Summary

StoreProject is a comprehensive, multi-tiered retail management platform designed to scale from single kiosks to multi-national supermarket chains, primarily focusing on the African context (specifically Cameroon). It features an offline-capable POS architecture, robust role-based access control (RBAC), multi-branch tracking, inventory management, and extensive financial and operational reporting.

The architecture is built on .NET 8.0 and currently operates as a Modular Monolith using ASP.NET Core Web API, Entity Framework Core (MySQL), and Razor Pages for the user interface.

2. Solution Structure

The project is structured into four primary C# projects:

2.1 Store.Models (Domain Layer)

  • Purpose: Contains the shared contracts, Enums, DTOs, and Domain Entities.
  • Key Components:
    • Entities: Extremely robust data model encompassing Branch, Customer, Employee, Invoice, PurchaseOrder, Sale, StockMovement, Item, User, CashierShift, and loyalty/campaign modules.
    • DTOs: Data Transfer Objects used to transport data cleanly between the API and UI layers without exposing internal entity states.
    • Interfaces: Defines service contracts that are implemented in DbServices or API application layers.

2.2 Store.DbServices (Data Access & Infrastructure Layer)

  • Purpose: Encapsulates all data persistence logic and infrastructure integrations.
  • Key Components:
    • Context (StoreDbContext): The central EF Core context managing the mappings between C# entities and the underlying MySQL tables.
    • Repositories & UnitOfWork: Implements the Repository and Unit of Work patterns to provide a clean abstraction over EF Core, ensuring transactional integrity.
    • Seeding: Automatically seeds essential foundational data (like Admin users and basic roles/permissions) on initialization.

2.3 Store.API (Application & Service Layer)

  • Purpose: The RESTful API that handles business logic, security, and data aggregation.
  • Key Components:
    • Program.cs: Configures the HTTP pipeline, rate-limiting (strict limits on /auth, broader limits elsewhere), JWT Bearer authentication, and Swagger with JWT support.
    • Controllers: Grouped by domain (e.g., AuthController, InvoicesController, InventoryOperationsController, CashManagementController, LoyaltyController, StockTransfersController).
    • Middleware: Global exception handling, correlation ID tracking, audit logging, and security header injection.
    • Authorization: Policies evaluate perm claims to gate operations (e.g., InventoryRead, PricingWrite).

2.4 Store.UI (Presentation Layer)

  • Purpose: A server-rendered Razor Pages application that acts as the back-office and POS terminal.
  • Key Components:
    • Program.cs: Configures Session state, Anti-forgery tokens, and registers HttpClient factories to communicate with the Store.API.
    • Pages: Mirrors the API domains (e.g., Pos.cshtml, BranchAdmin.cshtml, Dashboard.cshtml, StockTransfers.cshtml, RoleMatrix.cshtml).
    • Design System: Incorporates an Azure-inspired design paradigm (defined in docs/ui-ui_design.md) featuring blade navigation, dense data tables, command bars, and a Fluent-based styling token set.

3. Core Business Domains

The platform is designed to handle the end-to-end retail lifecycle:

  • Identity & Access Management: Managed via JWT, Users, Roles, and granular Privileges. It tracks users across branches (UserBranchRole).
  • Inventory & Warehouse: Handles batches, expiries, stock transfers between branches, goods receipt, wastage (WastageEntry), and reorder suggestions.
  • Pricing & Promotions: Rules engine for bundle pricing, customer segment pricing, and manager-overridden discounts.
  • Cash Management: Supports cashier shifts, Z-reports, cash variance tracking, and multiple tender types (including Mobile Money integrations).
  • Loyalty & Customer Engagement: Manages customer profiles, loyalty points (CustomerLoyaltyAccount, LoyaltyTransaction), and campaigns.
  • Procurement: End-to-end purchase orders and supplier management (PurchaseOrder, Supplier).

4. Architectural Highlights & Patterns

  1. Modular Monolith: Organized clearly into domains to allow future separation into microservices (e.g., Inventory, Payments) if scaling demands it.
  2. Security-First Approach: Implementation of strict CORS, Rate Limiting, HttpOnly SameSite=Strict cookies in UI, Anti-forgery, and Audit Logging middleware.
  3. Offline-First Readiness: The API and data model are structured to support idempotency and sync operations for POS terminals facing connectivity issues (crucial for the African market context).
  4. Resilient Communication: The UI communicates exclusively via an IApiClientService layer, ensuring a clean separation between frontend display and backend data operations.

5. Summary

The codebase is very mature, well-structured, and explicitly aligned with its Software Requirements Specification (SRS). It heavily leverages ASP.NET Core 8 features (like minimal configuration in Program.cs, advanced policy-based authorization, and rate limiting) and provides a highly scalable foundation for a multi-branch retail network.