1. System Overview

Levi’s Buy Plan Platform · architecture as it stands in v2

current state

as of v2 · Jul 2026

1.1 System overview

The Buy Plan Platform supports Levi’s seasonal inventory planning across up to 500 franchise stores and 50–100 concurrent users. Planners work store by store through a four-level merchandise hierarchy (GenCat → Brick → Platform → Fit), editing Width and distribution percentages against AI-generated recommendations, with Depth derived automatically; admins manage users, monitor franchisee engagement, and export finished plans to Excel. Each planning season runs in its own isolated environment, so historical seasons remain intact while a new season is planned.

Architecturally it is a deliberately simple three-tier system: a React single-page application served from AWS Amplify, a NestJS modular-monolith API on a single EC2 instance (Docker), and Aurora Serverless PostgreSQL using a schema-per-environment pattern for seasonal isolation. Files (uploads and Excel exports) live in S3; transactional email (OTP login, onboarding) goes out through SendGrid. The design accepts single-instance trade-offs by choice — planning is seasonal, non-transactional work where brief off-peak interruptions are acceptable — and prioritizes operational simplicity and cost over high availability.

1.2 Architecture

Architecture152K source lines

FEFrontend82K lines

React 18TypeScript Redux ToolkitMUI + Material React Table

7 feature areas · 4 planning views · token-driven design system

BEBackend69K lines

NestJSTypeScript REST APInode-postgres (parameterized SQL)

12 modules · 15 controllers · 70 REST endpoints

DATA

AWS Aurora Serverless · PostgreSQL

schema-per-environment isolation · 9 tables per seasonal environment + core schema · managed, single-AZ, encrypted (KMS)

INFRA

▣

EC2 + Docker

API hosting

▲

Amplify + S3

SPA hosting / CDN

◆

S3 (SSE-S3)

uploads & exports

≡

CloudWatch

logs · 30-day retention

✉

SendGrid SMTP

OTP & onboarding email

All client traffic over HTTPS/TLS 1.2+; no other public entry points. Line counts are application source excluding tests.

1.3 Module & component inventory

Backend — 12 modules (NestJS)

authmodule

OTP and password login, JWT issuance and validation, route guards and role checks, enumeration-safe responses, rate limiting and lockout.

usermodule

User directory (CRUD), six-role model, franchise-code assignment, bulk onboarding with one-time passwords and email, self-service profile and password change.

adminmodule

Engagement & finalization dashboard APIs: KPI summary, paginated franchisee list, per-store drill-down.

planningmodule

Core planning data: 4-level hierarchy reads/saves, width-led calculation validation, distribution normalization rules, reset-to-AI-recommendations, edit audit flags.

storemodule

Store master data, store status and finalization, franchise-scoped access checks.

uploadmodule

File uploads (store master, AI recommendations): validation, batch processing, progress tracking, user-edit preservation on re-upload.

exportmodule

Multi-sheet Excel workbook generation (5 sheets incl. Platform), asynchronous export jobs with status and expiry.

environmentmodule

Seasonal environment lifecycle: schema provisioning from the tenant template, activation, environment resolution per request.

reportsmodule

Reporting endpoints backing the dashboard and progress views.

auditmodule

Edit-audit metadata (who/when per change), access-decision logging.

migrationmodule

Schema and data migration utilities, including the idempotent backfill scripts for existing environments.

sharedmodule

Cross-cutting services: email (SMTP), structured logging with correlation IDs and masking, configuration, common utilities.

Frontend — 7 feature areas + platform layers (React)

planningfeature

The four planning views (GenCat, Brick, Platform, Fit): hierarchical grid, inline editing, client-side calculation engine (cascade/rollup/depth), per-view search, collapsible reference bands, reset-to-AI.

dashboardfeature

Landing dashboard with planning-progress counters filtered by role and franchise.

adminfeature

Admin screens: engagement & finalization dashboard, user management directory, uploads and environment administration.

authfeature

exportfeature

Excel export triggering and download handling.

reportsfeature

Report views over planning and store data.

profilefeature

Self-service profile and change-password screens.

themelayer

The v2 design-token system: single token source, resolver, 10 styled primitives, grid theming.

storelayer

Redux Toolkit state: planning data, drill-down state, session context.

shared / routerlayer

Layout chrome (header, navigation drawer, breadcrumbs), API client with auth header injection, route table.

1.4 Interconnects & third-party systems

How the components talk

Frontend → Backend: REST/JSON over HTTPS. Every authenticated request carries a JWT bearer token (12-hour TTL) and receives a correlation ID for end-to-end tracing; errors use a consistent envelope with generic auth failure messages.
Request pipeline (backend): environment lookup → database search_path selection for the caller’s seasonal schema → JWT guard → role guard → controller. The search path is reset when the connection returns to the pool, preventing cross-environment leakage.
Inside the backend: a modular monolith — modules communicate through direct service calls in-process (no queues, no internal network hops), with module boundaries enforced by convention and lint rules.
Data-level access: every query is filtered by the caller’s franchise assignments as parameterized SQL, independent of what the UI requests.

Third-party & platform services

Service	Type	Used for	Integration & failure policy
SendGrid	Third-party	OTP delivery, onboarding and notification email	SMTP via Nodemailer, API-key auth from environment variables (never logged); synchronous send with automatic retry for transient failures; email failures are audited and never block non-auth flows.
Aurora Serverless (PostgreSQL)	AWS platform	All application data	TLS connections, KMS encryption at rest, automated backups; schema-per-environment isolation.
S3	AWS platform	Upload staging, generated Excel exports	SSE-S3 encryption, lifecycle expiry for export files; export jobs tracked with status and expiry in the database.
Amplify Hosting	AWS platform	Serving the React SPA	Managed CDN with automatic HTTPS and cache invalidation on deploy.
CloudWatch	AWS platform	Application, error, and access logs	Structured JSON logs with correlation IDs and sensitive-data masking; 30-day retention.

There are no other external integrations — no third-party analytics, no payment systems, no outbound data sharing. The integration surface is intentionally minimal for a system of this scale.