Preface

Why This Book Exists

In late 2025, we embarked on a journey to replace an aging QuickBooks Point of Sale system with a modern, multi-tenant platform. What started as a simple migration project evolved into something much more ambitious: a comprehensive Blueprint for building enterprise-grade retail software.

This book captures everything we learned—the architecture decisions, the database designs, the implementation patterns, and the operational procedures. It’s not a theoretical exercise; it’s a practical guide born from real retail operations across five store locations.

The Three-Phase Philosophy

We adopted a deliberate three-phase approach:

╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║   PHASE 1: LEARN                    PHASE 2: DESIGN                      ║
║   ─────────────                     ──────────────                       ║
║   Build Stanly (bridge to QB)       Clean room architecture              ║
║   Build Raptag (RFID system)        Domain models without legacy         ║
║   Test with real stores             Database schema for scale            ║
║   Document every discovery          API specifications                   ║
║                                                                           ║
║                          ↓                                               ║
║                                                                           ║
║                    PHASE 3: BUILD                                        ║
║                    ──────────────                                        ║
║                    Fresh POS system from scratch                         ║
║                    Using learnings, not legacy code                      ║
║                    Multi-tenant from day one                             ║
║                    Production-grade quality                              ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

The critical insight: We don’t evolve legacy systems into production. We learn from them, then build fresh. This book is the culmination of Phase 2—the complete design that enables Phase 3.

What Makes This Blueprint Different

1. Self-Contained

Every diagram, code sample, and SQL statement is included directly in these pages. You won’t find “see external documentation” or “refer to file X.” Everything you need is here.

2. Production-Grade

This isn’t a prototype specification. The database schema has 69 tables. The API has 75+ endpoints. The architecture handles offline operations, multi-tenancy, and PCI-DSS compliance. We designed for the edge cases.

3. Claude Code Native

This Blueprint is designed to be built using Claude Code’s multi-agent orchestration. Every chapter includes the exact commands to implement each section. The book and the tool work together.

4. Battle-Tested Patterns

The patterns in this book come from real retail operations—from handling offline sales during network outages to reconciling inventory across multiple locations. These aren’t theoretical; they’re proven.

Who Should Read This Book

How to Use This Book

If Starting Fresh

Read sequentially from Part I through Part III. This gives you the full context before implementation.

If Joining Mid-Project

1. Read Part I (Foundation) for context
2. Read the relevant Part for your work area
3. Use Appendix F for BRD-to-code service mapping

If Looking Up Specific Information

Jump directly to:

• Ch 04 (Architecture Styles) for implementation patterns (~5,000 lines)
• Ch 05 (Architecture Components / BRD) for business requirements (~19,900 lines)
• Appendix F for BRD-to-code module mapping (142 services)

The Technology Stack

This Blueprint specifies a complete technology stack:

┌─────────────────────────────────────────────────────────────────────────┐
│                         TECHNOLOGY STACK                                │
│                                                                         │
│   BACKEND                          FRONTEND                             │
│   ───────                          ────────                             │
│   Node.js + TypeScript (API)       React/TypeScript (Nexus POS Web)    │
│   Prisma ORM                       React Native (Nexus Raptag)         │
│   PostgreSQL 16                    SQLite WASM (Offline Storage)       │
│   Socket.io (Real-time)            Vite + TailwindCSS + shadcn/ui     │
│                                                                         │
│   INFRASTRUCTURE                   INTEGRATIONS                         │
│   ──────────────                   ────────────                         │
│   Docker + Docker Compose          Shopify (E-commerce)                │
│   Prometheus + Grafana             Stripe/Square (Payments)            │
│   Redis 7.x (Caching)             Zebra (RFID Printers)               │
│   Tailscale (VPN Mesh)                                                 │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Conventions Used

Code Samples

// TypeScript code appears in blocks like this
export class OrderService {
  // Implementation
}

SQL Statements

-- SQL code appears in blocks like this
CREATE TABLE orders (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid()
);

Claude Commands

# Claude Code commands appear like this
/dev-team implement OrderService with event sourcing

Important Notes

Note: Important information appears in blockquotes like this.

Warning: Critical warnings that could cause issues.

Diagrams

ASCII diagrams are used throughout for portability:

┌─────────┐     ┌─────────┐     ┌─────────┐
│ Client  │────►│   API   │────►│Database │
└─────────┘     └─────────┘     └─────────┘

Acknowledgments

This Blueprint was created through collaboration between:

• Business stakeholders who defined the requirements
• Store employees who provided real-world feedback
• The Stanly project which taught us what works (and what doesn’t)
• The Raptag project which proved mobile RFID feasibility
• Claude Code agents who helped design, implement, and review

A Note on Quality

We set a goal: this system should be Grade A production quality. That means:

• Availability: 99.9% uptime (less than 9 hours downtime per year)
• Performance: Sub-2-second transaction completion
• Security: PCI-DSS compliant, zero card data storage
• Reliability: Works offline, syncs when connected
• Scalability: Multi-tenant from day one

Every design decision in this book was made with these targets in mind.

Let’s Build

You’re holding the complete Blueprint. The architecture is designed. The database is specified. The APIs are defined. The UI is wireframed. The operations procedures are documented.

All that’s left is to build it.

Turn the page and let’s begin.

December 2025

Document Information