lunarfront-app/planning/01_Overall_Architecture.md

Music Store Management Platform

Overall System Architecture

Version 1.0 | Draft

1. Executive Summary

This document describes the overall architecture of the Music Store Management Platform — a purpose-built system to replace AIM (Tri-Tech) for independent music retailers. The platform handles point-of-sale, inventory, rentals, lessons, repairs, customer management, financial reporting, and payment processing through a modern cloud-native stack.

2. System Overview

2.1 Goals

• Replace legacy AIM/MSSQL system with a modern, maintainable platform

• Support in-store desktop operations and mobile field sales (conventions)

• Provide customer-facing web portal for billing and repair status

• Enable clean migration of historical AIM data

• Support future multi-tenant expansion without full rewrite

2.2 Application Inventory

App

Technology

Purpose

Desktop

Electron + React

Full store management — POS, inventory, repairs, rentals, lessons, reporting

Mobile (iOS)

React Native

Field sales at conventions — POS, customer lookup, Stripe Terminal BT

Customer Portal

React (web)

Self-service — lesson billing, repair status, invoice history

Admin Panel

React (web)

Internal ops — users, settings, audit logs, migration tools, no payments

Backend API

Node.js / Python

REST API on AWS EKS — all business logic, Stripe integration, PDF generation

2.3 Monorepo Structure

/packages /shared ← TypeScript types, API clients, business logic, pricing engine /desktop ← Electron app (Windows/Mac/Linux) /mobile ← React Native iOS app /web-portal ← Customer-facing React web app /admin ← Internal admin React web app /backend ← Node.js/Python API server /migration ← AIM MSSQL → Postgres ETL scripts

3. Infrastructure

3.1 AWS Services

Service

Usage

EKS

Kubernetes cluster hosting API, admin panel, customer portal

Aurora PostgreSQL

Primary database — all domain data, append-only event sourcing pattern

ElastiCache (Redis)

Session cache, job queues, rate limiting

S3

PDF storage (invoices, reports), database backup archival, static assets

Secrets Manager

Stripe API keys, DB credentials, JWT secrets

CloudWatch

Logging, metrics, alerting

3.2 Database Backup Strategy

• Aurora automated continuous backup — point-in-time recovery up to 35 days

• Scheduled daily snapshots exported to S3 (separate bucket, cross-region)

• Long-term archival snapshots retained 1 year for financial compliance

• Recovery runbook documented and tested quarterly

• RTO target: 2 hours | RPO target: 1 hour

4. Payment Architecture

4.1 Stripe Integration

Stripe is the sole payment processor. All payment flows are handled through Stripe. Card data never touches application servers.

Feature

Usage

Stripe Terminal

In-person payments — WiFi reader (desktop), Bluetooth reader (iOS/mobile)

Stripe Elements

Keyed card entry on desktop — PCI-safe, card data goes direct to Stripe

Subscriptions

Recurring billing for lessons and rentals — monthly, with line items per enrollment

Webhooks

Async payment events — invoice.paid, payment_failed, subscription updates

Card Updater

Automatic card number updates when banks reissue — reduces billing failures

Stripe Connect

Architecture-ready for future multi-tenant expansion (not built initially)

4.2 Billing Model

• Accounts are the billing entity — one Stripe customer per account

• Students and rentals link to an account — family billing supported

• Subscriptions support multiple line items — consolidated billing option

• Split billing supported — separate subscriptions per enrollment if preferred

• Billing groups control consolidation — enrollments with same group_id share a subscription

5. Authentication & Authorization

• Auth provider: Clerk or Auth0 — handles user management, MFA, SSO

• Role-based access control: Admin, Manager, Technician, Instructor, Staff

• Customer portal uses separate auth flow (email/password or magic link)

• All API routes require JWT — validated on every request

• Sensitive operations (large discounts, refunds, write-offs) require manager role

6. Cross-Cutting Concerns

6.1 Audit Trail

Every discount, adjustment, price override, refund, and write-off is logged with: who, when, original value, new value, reason code, and whether approval was required. Audit records are append-only and cannot be deleted.

6.2 Multi-Tenant Readiness

All domain tables include a company_id column from day one — this is the tenant-scoping key. Tables dealing with physical inventory, transactions, cash drawers, and delivery also include a location_id column to identify the specific physical location. Business logic enforces company_id scoping on all queries. Stripe Connect architecture is documented but not implemented initially. Adding a second tenant is a configuration and billing exercise, not a rewrite.

6.3 Offline Support

The iOS mobile app supports offline mode for convention use. Transactions are queued locally and synced when connectivity is restored. The desktop app assumes reliable store network connectivity.

7. AIM Migration Strategy

7.1 Source System

AIM by Tri-Tech — Windows desktop POS running against a MSSQL (SQL Server Express) database on the store's local network. The application runs from a network share. Migration connects directly to MSSQL — AIM application is not involved.

7.2 Migration Phases

Phase

Scope

Notes

1

Schema exploration

Connect to AIM MSSQL, map tables to new domain model

2

ETL development

Python scripts: read AIM → transform → load Postgres staging

3

Data validation

Dry runs, exception logging, manual review of edge cases

4

Parallel operation

New system live for new customers, AIM continues for existing

5

Customer migration

Re-enroll active rentals/lessons in Stripe at renewal points

6

AIM wind-down

All recurring billing migrated, AIM read-only, close after chargeback window

7.3 Legacy Data Tagging

All migrated records include: legacy_id (AIM's original ID), legacy_source ('aim'), migrated_at timestamp, and requires_payment_update flag for records still on old processor.