System Design

Detailed system design and technical decisions.

Technology Stack

Frontend

Technology	Version	Purpose
Next.js	15.x	React framework
React	19.x	UI library
TypeScript	5.x	Type safety
Tailwind CSS	3.x	Styling
Radix UI	Latest	Components
Zustand	5.x	State management
SWR	2.x	Data fetching
Vitest	3.x	Unit testing
Playwright	Latest	E2E testing

Backend

Technology	Version	Purpose
Python	3.11+	Runtime
FastAPI	0.115+	API framework
SQLAlchemy	2.x	ORM
Alembic	1.x	Migrations
Redis	5.x	Caching
Pydantic	2.x	Validation
pytest	8.x	Testing

Infrastructure

Component	Technology
Hosting	Vercel (Frontend), Railway (Backend)
Database	MySQL 8.0+
Cache	Redis
CDN	Cloudflare
Monitoring	Sentry, OpenTelemetry

API Design

RESTful Conventions

GET    /api/v1/resources          # List
GET    /api/v1/resources/{id}     # Get one
POST   /api/v1/resources          # Create
PATCH  /api/v1/resources/{id}     # Update
DELETE /api/v1/resources/{id}     # Delete

Pagination

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 234,
    "total_pages": 5
  }
}

Error Handling

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "details": {
      "field": "email",
      "issue": "Invalid format"
    }
  }
}

Database Design

Core Tables

-- Users and authentication
users (id, email, password_hash, mfa_secret, ...)
user_sessions (id, user_id, token, expires_at, ...)

-- Business entities
entities (id, type, name, license_number, ...)
locations (id, entity_id, name, address, ...)

-- Products and inventory
products (id, entity_id, name, category, ...)
product_variants (id, product_id, sku, price, ...)
inventory (id, product_id, location_id, quantity, ...)

-- Orders
orders (id, retailer_id, wholesaler_id, status, ...)
order_items (id, order_id, product_id, quantity, ...)

Indexing Strategy

• Primary keys: UUID v4
• Foreign keys: Indexed automatically
• Search fields: Full-text indexes
• Query filters: Composite indexes

Caching Strategy

Cache Layers

1. Browser: Service worker, local storage
2. CDN: Static assets, API responses
3. Application: Redis for computed data
4. Database: Query cache

Cache Invalidation

• Time-based expiry (TTL)
• Event-based invalidation
• Manual purge capabilities

Real-time Features

WebSockets

Used for:

• Live inventory updates
• Order status changes
• Notifications

Polling Fallback

When WebSocket unavailable:

• 30-second polling interval
• Exponential backoff on errors

Background Processing

Job Types

Queue	Purpose
sync	POS synchronization
reports	Report generation
notifications	Email/SMS delivery
compliance	METRC reporting

Retry Policy

• 3 attempts
• Exponential backoff
• Dead letter queue for failures