System Architecture Diagrams

This section provides comprehensive architectural diagrams for the LUStores University Inventory Management System. These diagrams offer different perspectives on the system architecture, data flow, and operational workflows to help understand the system design and implementation.

Overview

The architectural diagrams are organized by perspective and audience:

  • Data Architecture: Database design and relationships

  • System Architecture: Overall system structure and components

  • Application Architecture: Frontend component organization

  • Security Architecture: Authentication and authorization flows

  • Infrastructure Architecture: Network and deployment design

  • Process Architecture: User workflows and business processes

Database Entity Relationships

The Entity Relationship Diagram (ERD) shows the complete database schema with all tables, relationships, and constraints.

erDiagram %% Core User Management users ||--o{ user_permissions : "has permissions" users ||--o{ items : "creates/updates" users ||--o{ stock_movements : "performs" users ||--o{ sales : "processes" users ||--o{ quotes : "creates/processes" users ||--o{ orders : "creates/receives" users ||--o{ chargecodes : "authorises" users ||--o{ charge_code_exclusions : "creates" users ||--o{ notes : "creates" %% Permission System permission_definitions ||--o{ user_permissions : "defines" %% Category System categories ||--o{ items : "categorizes" categories ||--o{ order_items : "applies to" categories ||--o{ charge_code_exclusions : "excludes" %% Item Management items ||--o{ stock_movements : "tracks changes" items ||--o{ sale_items : "sold as" items ||--o{ quote_items : "quoted as" items ||--o{ order_items : "ordered as" items ||--o{ sources : "supplied by" %% Supplier Relationships suppliers ||--o{ sources : "supplies items" suppliers ||--o{ orders : "receives orders" %% Sales System sales ||--o{ sale_items : "contains" %% Quote System quotes ||--o{ quote_items : "contains" %% Order Management orders ||--o{ order_items : "contains" %% Charge Codes chargecodes ||--o{ charge_code_exclusions : "has exclusions" chargecodes ||--o{ sales : "charged to" chargecodes ||--o{ quotes : "charged to" users { string id PK string email UK string password_hash "nullable" string first_name string last_name string role "default: user" boolean is_active "default: true" timestamp created_at timestamp updated_at } categories { serial id PK string name UK string description string icon "default: fas fa-box" string color "default: blue" timestamp created_at timestamp updated_at } items { serial id PK string name string sku UK string description integer category_id FK decimal price decimal vat_rate "default: 0.2000" boolean vat_included "default: true" integer current_stock "default: 0" integer minimum_stock "default: 0" boolean is_active "default: true" integer notes_id FK string created_by FK string updated_by FK timestamp created_at timestamp updated_at }

Key Database Features:

  • Referential Integrity: Foreign key constraints maintain data consistency

  • Audit Trails: Timestamp tracking and user attribution for all changes

  • Soft Deletes: Items marked inactive rather than deleted for history preservation

  • Polymorphic Notes: Single notes table references any entity type

  • Permission System: Granular role-based access control

See also

Database Schema Reference for detailed table specifications

System Architecture Flow

The system architecture diagram shows the complete technology stack from client to database with all major components and their relationships.

flowchart TD subgraph Client["Client Layer (React + TypeScript)"] Browser[Web Browser] React[React SPA] TanStack[TanStack Query] UI[Shadcn/UI Components] end subgraph Server["Server Layer (Node.js + Express)"] Express[Express Server] Routes[Route Handlers] AuthService[Authentication Service] Storage[Storage Layer] end subgraph AuthSystems["Authentication Systems"] LocalAuth[Local Authentication] SAML[SAML 2.0 SSO] UniversitySSO[University SSO] end subgraph Database["Database Layer (PostgreSQL)"] PG[PostgreSQL Database] Tables[Database Tables] Indexes[Indexes & Constraints] end Client --> Server Server --> AuthSystems Server --> Database

Architecture Principles:

  • Separation of Concerns: Clear boundaries between presentation, business logic, and data layers

  • Security First: Multiple authentication methods and comprehensive permission system

  • Type Safety: TypeScript throughout the entire stack

  • Performance: Connection pooling, query optimization, and intelligent caching

  • Scalability: Microservice-ready architecture with horizontal scaling support

Application Component Flow

The frontend component hierarchy shows React component relationships and data flow patterns throughout the user interface.

flowchart TD subgraph App["Main Application"] AppRoot[App Root Component] Router[React Router] AuthProvider[Authentication Provider] QueryClient[TanStack Query Client] end subgraph Pages["Page Components"] Dashboard[Dashboard Page] Inventory[Inventory Page] Orders[Orders Page] Sales[Sales Page] Quotes[Quotes Page] end subgraph SharedUI["Shared UI Components"] Dialog[Dialog/Modal] Table[Data Table] Form[Form Components] Button[Button Components] end subgraph DataHooks["Data Management Hooks"] useItems[useItems Hook] useOrders[useOrders Hook] useSales[useSales Hook] useQuotes[useQuotes Hook] end App --> Pages Pages --> SharedUI Pages --> DataHooks

Component Design Patterns:

  • Container/Presentational: Separation of data logic from UI presentation

  • Compound Components: Complex UI components built from smaller, reusable parts

  • Custom Hooks: Encapsulated data fetching and state management logic

  • Provider Pattern: Context-based state sharing across component trees

Authentication Flow

The authentication workflow diagram shows all supported login methods and security processes.

flowchart TD subgraph Entry["User Entry Points"] Browser[Web Browser] LoginPage[Login Page] end subgraph AuthMethods["Authentication Methods"] LocalAuth[Local Authentication] UniversitySSO[University SSO] SAML_Auth[SAML 2.0 SSO] end subgraph SessionMgmt["Session Management"] SessionStore[Session Storage] TokenRefresh[Token Refresh] PermissionCheck[Permission Verification] end subgraph Success["Successful Authentication"] UserContext[User Context Provider] AppDashboard[Application Dashboard] end Entry --> AuthMethods AuthMethods --> SessionMgmt SessionMgmt --> Success

Security Features:

  • Multi-Provider Authentication: Local, SSO, and SAML 2.0 support

  • Session Security: HTTP-only cookies, CSRF protection, secure transmission

  • Permission System: Role-based access control with granular permissions

  • Audit Logging: Comprehensive security event tracking

Data Flow Diagram

The data flow diagram illustrates how information moves through system layers during key business operations.

flowchart TD subgraph UI["User Interface Layer"] DashboardUI[📊 Dashboard] InventoryUI[📦 Inventory Management] OrdersUI[📋 Orders Management] SalesUI[💰 Sales Processing] end subgraph Business["Business Logic Layer"] AuthService[🔒 Authentication Service] InventoryService[📦 Inventory Service] OrderService[📋 Order Service] SalesService[💰 Sales Service] end subgraph DataAccess["Data Access Layer"] UserRepo[👤 User Repository] ItemRepo[📦 Item Repository] OrderRepo[📋 Order Repository] SalesRepo[💰 Sales Repository] end subgraph Database["Database Layer"] UserTables[(👤 Users & Permissions)] InventoryTables[(📦 Items & Categories)] TransactionTables[(💰 Sales & Quotes)] OrderTables[(📋 Orders & Suppliers)] end UI --> Business Business --> DataAccess DataAccess --> Database

Data Processing Features:

  • Input Validation: Multi-layer validation from client to database

  • Business Rule Enforcement: Complex business logic handled at service layer

  • Transaction Management: ACID compliance for multi-table operations

  • Audit Trail Generation: Automatic logging of all significant data changes

Network Flow Diagram

The network architecture shows infrastructure components, traffic flow, and security zones.

flowchart TD subgraph Internet["Internet 🌐"] Client[Client Browser] University[University SSO] end subgraph Edge["Edge Layer"] LoadBalancer[Load Balancer<br/>Traffic Distribution] SSL_Termination[SSL Termination<br/>HTTPS to HTTP] Firewall[Web Application Firewall<br/>Attack Prevention] end subgraph AppLayer["Application Layer"] WebServer[Web Server<br/>Nginx/Express] AppServer1[App Server 1<br/>Node.js Instance] AppServer2[App Server 2<br/>Node.js Instance] end subgraph DBLayer["Database Layer"] PrimaryDB[Primary Database<br/>PostgreSQL Master] ReplicaDB[Read Replica<br/>PostgreSQL Replica] end Internet --> Edge Edge --> AppLayer AppLayer --> DBLayer

Network Security:

  • DMZ Architecture: Public-facing services isolated from internal systems

  • SSL/TLS Encryption: End-to-end encryption for all client communication

  • Network Segmentation: Layered security with restricted inter-zone access

  • Load Balancing: High availability with automatic failover capabilities

Deployment Architecture

The deployment diagram shows infrastructure across development, staging, and production environments.

flowchart TD subgraph Dev["Development Environment"] DevMachine[Developer Machine] DevDocker[Docker Desktop] DevDB[Local PostgreSQL] end subgraph CICD["CI/CD Pipeline"] GitHub[GitHub Repository] Actions[GitHub Actions] Registry[Container Registry] end subgraph Prod["Production Environment"] ProdLB[Production Load Balancer] ProdApp1[App Server 1] ProdApp2[App Server 2] ProdDB[Production Database] end subgraph Monitor["Monitoring"] Prometheus[Prometheus] Grafana[Grafana] AlertManager[Alert Manager] end Dev --> CICD CICD --> Prod Monitor --> Prod

Deployment Strategy:

  • Containerization: Docker containers for consistent deployment across environments

  • Blue-Green Deployment: Zero-downtime deployments with instant rollback capability

  • Infrastructure as Code: Terraform and automated provisioning

  • Monitoring Integration: Comprehensive observability with Prometheus and Grafana

User Workflow Sequences

The sequence diagrams show step-by-step interactions for key business processes.

Authentication Sequence:

sequenceDiagram participant U as User participant App as Application participant SSO as University SSO participant DB as Database U->>App: Access application App-->>U: Redirect to login U->>App: Select SSO login App->>SSO: Redirect to SSO provider SSO->>U: Show university login U->>SSO: Enter credentials SSO->>App: SAML response with user data App->>DB: Query/create user record DB-->>App: User data App-->>U: Show dashboard

Order Processing Sequence:

sequenceDiagram participant U as User participant UI as Orders UI participant API as API Server participant Orders as Order Service participant DB as Database U->>UI: Upload PDF invoice UI->>API: POST /api/orders/import API->>Orders: Create order from parsed data Orders->>DB: INSERT order and items Orders-->>API: Order created successfully API-->>UI: 201 Created + order data UI-->>U: Show order confirmation

Workflow Characteristics:

  • Error Handling: Comprehensive error paths and rollback mechanisms

  • Transaction Safety: Database transactions ensure data consistency

  • Real-time Updates: UI immediately reflects server-side changes

  • Audit Integration: All significant actions logged for compliance

Using the Diagrams

For Software Architects:

Start with the System Architecture Flow for overall understanding, then drill down into specific areas using the specialized diagrams.

For Developers:

Reference the Application Component Flow for frontend work and Sequence Diagrams for business logic implementation.

For DevOps Engineers:

Focus on the Deployment and Network Flow diagrams for infrastructure planning and configuration.

For Business Stakeholders:

Use the Data Flow and Sequence diagrams to understand business processes and system capabilities.

Note

All diagrams are created using Mermaid syntax and are version-controlled as text files in the /diagrams directory. They can be easily updated and automatically render in most documentation platforms.

See also