Muse & Co Wiki

Appearance

Architecture Overview ​

System architecture for Muse & Co applications

Developer Documentation

This page is for developers and technical staff. For operational procedures, see other sections of the wiki.

System Architecture ​

Muse & Co uses a modern, cloud-native architecture built on Cloudflare's edge platform.

┌─────────────────────────────────────────────────────────────┐
│                         USERS                               │
│                                                             │
│  ┌──────────────────┐          ┌──────────────────┐       │
│  │   Customers      │          │   Staff/Admin    │       │
│  │  (ncmuse.co)     │          │ (staff.ncmuse.co)│       │
│  └────────┬─────────┘          └─────────┬────────┘       │
└───────────┼──────────────────────────────┼────────────────┘
            │                              │
            v                              v
┌───────────────────────────────────────────────────────────┐
│              CLOUDFLARE EDGE NETWORK                      │
│                                                           │
│  ┌──────────────────┐          ┌──────────────────┐     │
│  │  muse-customer   │          │   muse-admin     │     │
│  │   (Vite + React) │◄────────►│  (Vite + React)  │     │
│  │  Pages + Workers │   CORS   │ Pages + Workers  │     │
│  └────────┬─────────┘          └─────────┬────────┘     │
│           │                              │              │
│           └──────────┬───────────────────┘              │
│                      v                                   │
│           ┌──────────────────────┐                      │
│           │   Cloudflare D1      │                      │
│           │  (SQLite Database)   │                      │
│           └──────────────────────┘                      │
└───────────────────────────────────────────────────────────┘
            │                              │
            v                              v
┌───────────────────────────────────────────────────────────┐
│              EXTERNAL SERVICES                            │
│                                                           │
│  ┌────────────┐  ┌────────────┐  ┌─────────────┐       │
│  │   Stripe   │  │  AWS SES   │  │ Cloudflare  │       │
│  │  Payments  │  │   Email    │  │     R2      │       │
│  └────────────┘  └────────────┘  └─────────────┘       │
└───────────────────────────────────────────────────────────┘

Dual-App Architecture ​

Why Two Separate Apps? ​

Muse & Co is built as two independent applications that share a database:

  1. muse-customer (ncmuse.co)

    • Customer-facing portal
    • Menu browsing and ordering
    • Membership purchases
    • Event bookings

  2. muse-admin (staff.ncmuse.co)

    • Staff/manager portal
    • Order management
    • Menu administration
    • Analytics and reporting

Benefits of Dual-App Design ​

1. Smaller Bundle Sizes

  • Customer app doesn't include admin code
  • Admin app doesn't include customer features
  • Faster page loads for both audiences

2. Independent Deployments

  • Update customer app without touching admin
  • Fix admin bugs without affecting customers
  • Different deployment schedules

3. Better Security

  • Admin functions completely isolated
  • No admin routes accessible from customer domain
  • Separate authentication contexts

4. Faster Development

  • Smaller codebases to navigate
  • Clearer separation of concerns
  • Easier to reason about each app

5. Performance Optimization

  • Each app optimized for its use case
  • Different caching strategies
  • Tailored build configurations

Technology Stack ​

Frontend ​

Build Tool: Vite

  • Fast development server with HMR
  • Optimized production builds
  • Modern JavaScript/TypeScript support

Framework: React

  • Component-based architecture
  • Hooks for state management
  • TypeScript for type safety

UI Components:

  • Custom component library
  • Consistent design system
  • Responsive mobile-first design

Backend / API Layer ​

Platform: Cloudflare Workers

  • Serverless functions at the edge
  • Sub-millisecond cold starts
  • Global distribution

API Pattern:

  • RESTful endpoints
  • JSON request/response
  • CORS-enabled for cross-portal calls

Database ​

Cloudflare D1

  • SQLite at the edge
  • Sub-millisecond query performance
  • Built-in replication

Performance:

  • Typical queries: 0.3-0.7ms
  • No cold starts
  • Near-zero latency

Design Principles:

  • Normalized data structure
  • JSON fields for flexibility
  • Indexes on frequently queried columns
  • Version tracking for cache invalidation

Authentication ​

Customer Portal:

  • Email/password authentication
  • OAuth providers (Google, Facebook)
  • Session-based with secure cookies
  • Account linking for OAuth users

Admin Portal:

  • Email/password (staff only)
  • Role-based access control
  • Separate authentication context

External Integrations ​

Stripe

  • Payment processing
  • Subscription management
  • Webhook event handling
  • Test/Live mode switching

AWS SES

  • Transactional emails
  • Order confirmations
  • Event notifications
  • Centralized in muse-customer

Cloudflare R2

  • Image storage
  • Menu item photos
  • Event images
  • CDN-optimized delivery

Data Flow Examples ​

Customer Ordering Flow ​

1. Customer browses menu (muse-customer)
   └─> Queries D1 database for menu items

2. Customer adds items to cart (frontend state)

3. Customer checks out
   └─> Creates Stripe Checkout Session
   └─> Stores pending order in D1

4. Customer completes payment (Stripe)

5. Stripe sends webhook to muse-customer
   └─> Verifies webhook signature
   └─> Updates order status in D1
   └─> Sends confirmation email via AWS SES

6. Admin sees new order (muse-admin)
   └─> Queries D1 for recent orders
   └─> Displays in order management interface

Admin Menu Update Flow ​

1. Admin updates menu item (muse-admin)
   └─> Updates D1 database
   └─> Increments cache version

2. Customer app cache invalidates
   └─> Detects version change
   └─> Refreshes menu data from D1

3. Customers see updated menu immediately

Cross-Portal Email Flow ​

1. Admin sends notification (muse-admin)
   └─> Calls muse-customer API endpoint
   └─> CORS allows cross-domain request

2. muse-customer /api/send-email processes request
   └─> Validates request
   └─> Formats email HTML
   └─> Sends via AWS SES v2 API

3. Customer receives email

Shared Resources ​

Database Sharing ​

Both apps share the same D1 database but with different bindings:

muse-customer wrangler.toml:

toml
[[d1_databases]]
binding = "DB"
database_name = "muse-and-co-db"
database_id = "[DATABASE_ID]"

muse-admin wrangler.toml:

toml
[[d1_databases]]
binding = "DB"
database_name = "muse-and-co-db"
database_id = "[DATABASE_ID]"

Both apps can read and write, but admin has exclusive access to certain management functions.

API Sharing ​

Email Service (Centralized):

  • Implemented in muse-customer
  • Admin calls customer API for email sending
  • Single source of truth for email templates
  • No credential duplication

CORS Configuration:

typescript
const allowedOrigins = [
  'https://ncmuse.co',
  'https://staff.ncmuse.co',
  'https://localhost:5173', // Dev
  // Preview URLs also allowed during development
];

Security Architecture ​

Authentication Boundaries ​

Customer Portal:

  • Public access for browsing
  • Authentication required for orders/membership
  • Session cookies (HttpOnly, Secure, SameSite)

Admin Portal:

  • No public access
  • Authentication required for all pages
  • Staff-only email domains enforced

API Security ​

Rate Limiting:

  • 20 requests/minute per IP (configurable)
  • Prevents brute force attacks
  • Protects against abuse

Input Sanitization:

  • HTML tag removal
  • SQL injection pattern detection
  • Request size limits (10KB max)

CORS Protection:

  • Whitelist of allowed origins
  • No wildcard origins in production
  • Preflight request handling

Webhook Verification:

  • HMAC signature validation (Stripe)
  • Timing-safe comparison
  • Replay attack prevention

Environment Management ​

Environment Separation ​

Development:

  • localhost:5173 (Vite dev server)
  • Stripe test mode
  • Local D1 database
  • Console logging enabled

Preview:

  • Cloudflare preview URLs
  • Stripe test mode
  • Remote D1 database
  • Limited logging

Production:

  • Custom domains (ncmuse.co, staff.ncmuse.co)
  • Stripe live mode
  • Remote D1 database
  • Error logging only

Configuration ​

Frontend (.env files):

  • VITE_STRIPE_PUBLISHABLE_KEY
  • VITE_API_BASE_URL
  • VITE_SITE_URL

Backend (Cloudflare Secrets):

  • STRIPE_SECRET_KEY
  • STRIPE_WEBHOOK_SECRET
  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY

Performance Optimizations ​

Edge Computing ​

  • All compute runs at Cloudflare edge
  • Served from location nearest to user
  • Sub-50ms latency worldwide

Database Performance ​

  • D1 queries: 0.3-0.7ms typical
  • Indexed columns for fast lookups
  • Efficient query patterns
  • Connection pooling built-in

Caching Strategy ​

Menu Data:

  • Version-based cache invalidation
  • Cache key: menu:full:v${version}
  • Admin increments version on updates
  • Customer app checks version on each load

Static Assets:

  • CDN caching via Cloudflare
  • Long cache TTL for images
  • Cache busting via build hashes

Bundle Optimization ​

  • Code splitting by route
  • Dynamic imports for heavy components
  • Tree shaking of unused code
  • Minification and compression

Deployment Architecture ​

Build Pipeline ​

Code Changes (Git)
    ↓
Local Build (Vite)
    ↓
Deploy to Cloudflare Pages
    ↓
Automatic Distribution to Edge
    ↓
Custom Domain Propagation (1-2 min)

Deployment Strategy ​

Blue-Green Deployments:

  • New version deploys alongside old
  • Preview URL available immediately
  • Custom domain switches after verification
  • Instant rollback if needed

Database Migrations:

  • Run before code deployment
  • Backward compatible changes
  • Verify with test queries
  • Coordinated with code deploys

Monitoring & Observability ​

Available Metrics ​

Cloudflare Dashboard:

  • Request volume
  • Error rates
  • Response times
  • Bandwidth usage

Application Logs:

  • Error tracking (console.error)
  • Performance logging
  • User action tracking (orders, signups)

Error Handling ​

Frontend:

  • Error boundaries for React components
  • User-friendly error messages
  • Automatic retry for network failures

Backend:

  • Try-catch blocks on all API endpoints
  • Structured error responses
  • Error logging to Cloudflare

Future Architecture Plans ​

Planned Improvements ​

  1. Advanced Caching:

    • Cloudflare KV for menu caching
    • Multi-layer cache strategy
    • Smarter invalidation patterns

  2. Analytics Enhancement:

    • Cloudflare Analytics Engine
    • Real-time dashboards
    • Custom metrics tracking

  3. API Gateway:

    • Centralized API management
    • Better rate limiting
    • Request logging

  4. Testing Infrastructure:

    • Automated E2E tests
    • Preview environment testing
    • Load testing capabilities

Questions about architecture? Ask a senior developer or consult the technical documentation.

Internal documentation for Muse & Co staff only

Copyright © 2025 Muse & Co