⬅️ Back to Architecture Index

Frontend Architecture Overview

Introduction

Smart Supply Pro’s frontend is a React single-page application (SPA) that provides the user experience for inventory management, supplier workflows, and analytics. The architecture documentation focuses on clarity, consistency, and maintainability by describing how the application is organized into topics (routing, state, data access, UI, etc.) and how those topics fit together.

For diagrams and visual references, start at Architectural Diagrams.

System Context (high-level)

graph LR User["User"] --> Browser["Browser"] Browser --> SPA["Frontend SPA (React)"] SPA --> API["Backend API"] API --> DB["Database"]

Documentation Scope

This overview intentionally avoids implementation details. Each topic below links to its dedicated section where patterns, decisions, and examples will be documented.

Topics (and where to find diagrams)

Each topic links to: - the topic documentation folder, and - the diagrams entry point (centralized under ./diagrams/index.md).

App Shell

  • Docs: App Shell
  • Diagrams: Architectural Diagrams
  • Description: Entry point for shell variants (public vs authenticated), layout composition, preference handling (theme/locale), toasts, settings entry points, and help integration

Routing

  • Docs: Routing
  • Diagrams: Architectural Diagrams
  • Description: How URLs map to pages, how routes are grouped (public vs authenticated), guard/redirect behavior, logout/session-expiry navigation, and 404 fallback

State

  • Docs: State
  • Diagrams: Architectural Diagrams
  • Description: Global cross-cutting state via React Context (auth, settings, toast, help) and the boundaries vs local UI state and server state

Data Access

  • Docs: Data Access
  • Diagrams: Architectural Diagrams
  • Description: API layer structure (Axios client, domain fetchers/normalizers, React Query hooks), caching conventions, envelope tolerance, and user-friendly error handling

Domains

  • Docs: Domains
  • Diagrams: Architectural Diagrams
  • Description: How domain pages are organized under src/pages/* (Inventory, Suppliers, Analytics, etc.), and what each page orchestrator owns vs shared layers

UI Components

  • Docs: UI & UX Building Blocks
  • Diagrams: Architectural Diagrams
  • Description: Shared UI building blocks (e.g. StatCard), shared hooks (createContextHook, debounce), help topics + trigger button, and the health-check polling hook

Theming

  • Docs: Theme & Styling
  • Diagrams: Architectural Diagrams
  • Description: MUI theme factory (buildTheme), locale packs (Material + DataGrid), compact density defaults, and the small set of global CSS helpers

Internationalization (i18n)

Performance

  • Docs: Performance
  • Diagrams: Architectural Diagrams
  • Description: Bundle strategy, (future) lazy loading seams, rendering optimization for tables/dialog-heavy workflows/analytics blocks, API caching (React Query), and build + delivery behavior

Testing

  • Docs: Testing
  • Diagrams: Architectural Diagrams
  • Description: Testing architecture and conventions (layers/pyramid, directory taxonomy, mocking policy, shared render helpers/providers, and coverage interpretation)

Architectural Decision Records (ADRs)

  • Docs: ADRs
  • Diagrams: Architectural Diagrams
  • Description: “Why” decisions for key architectural choices (folder strategy, API abstraction, page model, dialog workflows, shell split, context-based global state, i18n integration, and testing taxonomy)

Next Steps

  1. Read the topic that matches your current task (routing/state/data-access/ui).
  2. Use Architectural Diagrams as the single entry point for visuals.
  3. Update each topic’s short description as the documentation evolves.

⬅️ Back to Architecture Index