System Architecture

This document provides a comprehensive overview of the University Inventory Management System architecture, including component relationships, data flow, and design decisions.

Overview

The system follows a modern full-stack architecture with clear separation of concerns:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Client (React)│    │  Server (Node)  │    │ Database (PG)   │
│                 │◄──►│                 │◄──►│                 │
│ - UI Components │    │ - REST API      │    │ - Tables        │
│ - State Mgmt    │    │ - Auth          │    │ - Relations     │
│ - Routing       │    │ - Business Logic│    │ - Indexes       │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Architecture Principles

Single Page Application (SPA)

React-based frontend with client-side routing
API-driven architecture for data operations
Responsive design for mobile compatibility

RESTful API Design

Consistent endpoint structure
HTTP status codes for operation results
JSON request/response format

Database-First Approach

Schema-driven development using Drizzle ORM
Type-safe database operations
Automated migrations and schema validation

Security by Design

Authentication required for all operations
Role-based access control (RBAC)
Session management with secure cookies

Technology Stack

Frontend Technologies

Core Framework

React 18: Modern component-based UI library
TypeScript: Type safety and developer experience
Vite: Fast development server and build tool

UI Components

Tailwind CSS: Utility-first CSS framework
Shadcn/UI: Pre-built accessible components
Lucide Icons: Consistent iconography
Radix UI: Headless component primitives

State Management

TanStack Query: Server state management and caching
React Hook Form: Form state and validation
Zod: Runtime type validation

Routing

Wouter: Lightweight client-side routing
History API: Browser navigation support

Backend Technologies

Runtime & Framework

Node.js 20: JavaScript runtime environment
Express.js: Web application framework
TypeScript: Type-safe server development

Database & ORM

PostgreSQL: Relational database system
Drizzle ORM: Type-safe database toolkit
Connection Pooling: Optimized database connections

Authentication

Passport.js: Authentication middleware
SAML 2.0: University SSO integration
Express Sessions: Session management

Development Tools

TSX: TypeScript execution
ESLint: Code linting
Prettier: Code formatting

File Structure and Layout

Project Root Structure

university-inventory/
├── client/                 # Frontend React application
│   ├── src/
│   │   ├── components/     # Reusable UI components
│   │   ├── pages/         # Route-specific page components
│   │   ├── hooks/         # Custom React hooks
│   │   ├── lib/           # Utility functions and configurations
│   │   ├── App.tsx        # Main application component
│   │   ├── main.tsx       # Application entry point
│   │   └── index.css      # Global styles
│   └── index.html         # HTML template
├── server/                # Backend Node.js application
│   ├── db.ts             # Database connection setup
│   ├── index.ts          # Server entry point
│   ├── routes.ts         # API route definitions
│   ├── storage.ts        # Data access layer
│   ├── replitAuth.ts     # Replit OAuth implementation
│   ├── universitySso.ts  # SAML SSO implementation
│   └── vite.ts           # Development server integration
├── shared/               # Shared code between client/server
│   └── schema.ts         # Database schema and types
├── docs/                 # Documentation source files
│   ├── api/             # API documentation
│   ├── tutorials/       # Step-by-step guides
│   ├── user-guide/      # User documentation
│   ├── development/     # Developer documentation
│   └── deployment/      # Deployment guides
├── .github/             # GitHub workflows
│   └── workflows/       # CI/CD pipeline definitions
├── package.json         # Node.js dependencies and scripts
├── tsconfig.json        # TypeScript configuration
├── tailwind.config.ts   # Tailwind CSS configuration
├── vite.config.ts       # Vite build configuration
└── Dockerfile           # Container deployment configuration

Frontend Architecture

Component Hierarchy

App.tsx
├── Router (wouter)
│   ├── Landing.tsx (unauthenticated)
│   └── Authenticated Routes
│       ├── Dashboard.tsx
│       │   ├── StatsCards.tsx
│       │   ├── SidePanel.tsx
│       │   └── InventoryTable.tsx
│       ├── Inventory.tsx
│       │   ├── ItemModal.tsx
│       │   └── InventoryTable.tsx
│       ├── Reports.tsx
│       ├── Users.tsx (admin only)
│       └── Documentation.tsx
└── Layout Components
    ├── TopBar.tsx
    ├── Sidebar.tsx
    └── UI Components (shadcn/ui)

State Management Strategy

Server State (TanStack Query)

API data fetching and caching
Background refetching
Optimistic updates
Error handling

Client State (React State)

UI state (modals, forms)
Component-specific state
Temporary data

Form State (React Hook Form)

Form validation
Field-level state
Submission handling

Data Flow Patterns

Read Operations

Component mounts
TanStack Query fetches data
Loading state displayed
Data received and cached
Component renders with data

Write Operations

User interaction triggers mutation
Optimistic update (optional)
API request sent
Success: Cache invalidated and refetched
Error: Rollback and show error message

Backend Architecture

Request Processing Flow

HTTP Request
│
├── Express Middleware Stack
│   ├── Session Management
│   ├── Authentication Check
│   ├── Role Authorization
│   └── Request Parsing
│
├── Route Handler
│   ├── Input Validation (Zod)
│   ├── Business Logic
│   └── Storage Operations
│
├── Database Layer (Drizzle)
│   ├── Query Building
│   ├── Connection Pooling
│   └── Result Mapping
│
└── HTTP Response
    ├── Success: JSON Data
    └── Error: Error Object

API Design Patterns

RESTful Endpoints

GET /api/items - List resources
POST /api/items - Create resource
GET /api/items/:id - Get specific resource
PUT /api/items/:id - Update resource
DELETE /api/items/:id - Delete resource

Response Format

{
  "data": { /* resource data */ },
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 10
  }
}

Error Format

{
  "error": "Validation failed",
  "message": "SKU is required",
  "code": "VALIDATION_ERROR",
  "details": { /* field errors */ }
}

Authentication Architecture

Multi-Provider Support

Check for SAML configuration
Initialize SAML strategy if available
Fallback to Replit OAuth
Session-based authentication

Middleware Chain

Session deserialization
User authentication check
Role-based authorization
Request processing

Session Management

PostgreSQL session store
Secure cookie configuration
Automatic session cleanup

Database Architecture

Schema Design

Core Tables

sessions: Session storage for authentication (Replit/local/SSO)
users: User accounts, roles, and profile info
categories: Inventory categories
items: Inventory items, linked to categories and users
stock_movements: Audit trail for stock changes, linked to items and users
sales: Completed sales transactions, linked to users
sale_items: Line items for each sale, linked to sales and items
quotes: Draft quotes, linked to users
quote_items: Line items for each quote, linked to quotes and items
suppliers: Supplier information
sources: Many-to-many link between items and suppliers
orders: Bulk procurement orders, linked to suppliers and users
order_items: Items in each order, linked to orders, items, and categories
chargecodes: Charge code definitions, linked to users
charge_code_exclusions: Exclusions for charge codes by category, linked to users
system_settings: Configurable system settings
user_permissions: Granular user permissions, linked to users
permission_definitions: Permission definitions and default roles
system_tests: System test results

Relationship Patterns

One-to-Many: categories → items, users → items, users → stock_movements, users → sales, users → orders, orders → order_items, sales → sale_items, quotes → quote_items
Many-to-Many: items ↔ suppliers (via sources)
Charge code exclusions: chargecodes → categories (via charge_code_exclusions)

Indexing Strategy

Primary keys for unique identification
Foreign keys for relationship integrity
Search indexes on frequently queried fields (e.g., sessions.expire)
Composite/unique indexes for complex queries and constraints

Schema File

The schema is defined in /shared/schema.ts using Drizzle ORM and Zod for type safety and validation.

TypeScript Types

All table types and insert/update types are exported from /shared/schema.ts for use across backend and (optionally) frontend.

Notes

All tables use snake_case naming in the database.
Foreign keys are enforced for all relationships.
Timestamps (createdAt, updatedAt) are present on most tables.
Role-based access and permissions are managed via users, user_permissions, and permission_definitions.

Data Access Layer

Storage Interface Pattern

Abstract interface defining operations
Concrete implementation with database logic
Type-safe operations using Drizzle
Transaction support for complex operations

Query Optimization

Connection pooling for performance
Prepared statements for security
Selective field loading
Pagination for large datasets

Security Architecture

Authentication Security

SAML 2.0 Implementation

Certificate-based signature verification
Encrypted assertion support
Clock skew tolerance
Replay attack prevention

Session Security

HTTP-only cookies
Secure flag for HTTPS
SameSite protection
Session rotation

Authorization Model

Role-Based Access Control (RBAC)

Three-tier role system (User, Manager, Admin)
Middleware-enforced permissions
API-level authorization checks
UI-level role-based rendering

Data Security

Input validation using Zod schemas
SQL injection prevention via ORM
XSS protection through React’s default escaping
CSRF protection via SameSite cookies

Deployment Architecture

Development Environment

Development Server (Vite)
├── Hot Module Replacement
├── TypeScript Compilation
├── CSS Processing
└── Proxy to Express API

Express Server
├── API Routes
├── Authentication
├── Database Connection
└── Static File Serving

Production Environment

Load Balancer
│
├── Application Servers (Node.js)
│   ├── Express Application
│   ├── Session Store (PostgreSQL)
│   └── Health Checks
│
├── Database Cluster (PostgreSQL)
│   ├── Primary (Read/Write)
│   ├── Replica (Read Only)
│   └── Backup Storage
│
└── Static Assets (CDN)
    ├── Built Frontend
    ├── Documentation
    └── Media Files

Containerization

Multi-Stage Docker Build

Base Stage: Node.js and dependencies
Development Stage: Development tools and hot reload
Build Stage: Production build and documentation
Production Stage: Minimal runtime environment

Container Orchestration

Docker Compose for local development
Health checks for container monitoring
Volume mounts for persistent data
Environment-based configuration

Performance Considerations

Frontend Performance

Code Splitting

Route-based code splitting
Dynamic imports for large components
Lazy loading of non-critical features

Caching Strategy

TanStack Query for API response caching
Browser caching for static assets
Service worker for offline support (future)

Bundle Optimization

Tree shaking for unused code elimination
Minification for production builds
Gzip compression for assets

Backend Performance

Database Optimization

Connection pooling (max 20 connections)
Query optimization with indexes
Pagination for large datasets
Selective field loading

Caching Layers

Application-level caching for computed data
Database query result caching
Session storage optimization

Resource Management

Memory usage monitoring
CPU usage optimization
Graceful shutdown handling

Monitoring and Observability

Application Metrics

Performance Metrics

Response time monitoring
Database query performance
Memory and CPU usage
Error rate tracking

Business Metrics

User activity tracking
Inventory turnover rates
System utilization
Feature usage analytics

Health Checks

Database connectivity
Authentication service status
External service dependencies
Application responsiveness

Logging Strategy

Log Levels

Error: System errors and exceptions
Warn: Performance issues and deprecations
Info: General application flow
Debug: Detailed troubleshooting information

Log Format

{
  "timestamp": "2025-01-20T10:30:00Z",
  "level": "info",
  "service": "inventory-api",
  "user": "user123",
  "action": "create_item",
  "details": { /* contextual data */ }
}

Future Architecture Considerations

Scalability Improvements

Horizontal Scaling

Stateless application design
Load balancer configuration
Database read replicas
Microservice migration path

Performance Enhancements

Redis caching layer
CDN integration
Database partitioning
Background job processing

Feature Enhancements

Real-time notifications
Advanced reporting engine
Mobile application
Integration APIs

This architecture documentation provides the foundation for understanding, maintaining, and extending the University Inventory Management System. For specific implementation details, refer to the individual component documentation and code comments.