The POS Platform Blueprint

A Complete Guide to Building an Enterprise Multi-Tenant Point of Sale System

Version: 5.1.0 Created: December 29, 2025 Updated: February 27, 2026 Target Platform: /volume1/docker/pos-platform/

╔═══════════════════════════════════════════════════════════════════════════════╗
║                                                                               ║
║                    ████████╗██╗  ██╗███████╗                                  ║
║                    ╚══██╔══╝██║  ██║██╔════╝                                  ║
║                       ██║   ███████║█████╗                                    ║
║                       ██║   ██╔══██║██╔══╝                                    ║
║                       ██║   ██║  ██║███████╗                                  ║
║                       ╚═╝   ╚═╝  ╚═╝╚══════╝                                  ║
║                                                                               ║
║           ██████╗  ██████╗ ███████╗    ██████╗ ██╗     ██╗   ██╗███████╗     ║
║           ██╔══██╗██╔═══██╗██╔════╝    ██╔══██╗██║     ██║   ██║██╔════╝     ║
║           ██████╔╝██║   ██║███████╗    ██████╔╝██║     ██║   ██║█████╗       ║
║           ██╔═══╝ ██║   ██║╚════██║    ██╔══██╗██║     ██║   ██║██╔══╝       ║
║           ██║     ╚██████╔╝███████║    ██████╔╝███████╗╚██████╔╝███████╗     ║
║           ╚═╝      ╚═════╝ ╚══════╝    ╚═════╝ ╚══════╝ ╚═════╝ ╚══════╝     ║
║                                                                               ║
║                        ██████╗ ██████╗ ██╗███╗   ██╗████████╗                ║
║                        ██╔══██╗██╔══██╗██║████╗  ██║╚══██╔══╝                ║
║                        ██████╔╝██████╔╝██║██╔██╗ ██║   ██║                   ║
║                        ██╔═══╝ ██╔══██╗██║██║╚██╗██║   ██║                   ║
║                        ██║     ██║  ██║██║██║ ╚████║   ██║                   ║
║                        ╚═╝     ╚═╝  ╚═╝╚═╝╚═╝  ╚═══╝   ╚═╝                   ║
║                                                                               ║
║                    Enterprise Multi-Tenant Point of Sale                      ║
║                          Architecture & Implementation                        ║
║                                                                               ║
╚═══════════════════════════════════════════════════════════════════════════════╝

How to Use This Book

This Blueprint is a self-contained guide for building a production-grade, multi-tenant POS system using Claude Code’s multi-agent orchestration. Every diagram, code sample, database schema, and implementation detail is included directly in these pages.

Reading Order

If You Want To…Start With…
Understand the visionPart I: Foundation
Design the systemPart II: Architecture
Build the databasePart III: Database
Write the backendPart IV: Backend
Create the UIPart V: Frontend
Start implementingPart VI: Implementation
Deploy to productionPart VII: Operations
Look up termsPart VIII: Reference

Claude Code Commands

Throughout this book, you’ll see commands like:

/dev-team implement tenant middleware

These are Claude Code multi-agent commands. See Chapter 29: Claude Code Reference for the complete command guide.

Table of Contents

Front Matter

Part I: Foundation (Chapter 01)

What this book is and how to use it

Part II: Architecture (Chapters 02-05)

System design, quality attributes, and key decisions

Note: In v3.0.0, standalone architecture chapters were consolidated into enriched Characteristics and Styles chapters. In v4.0.0, the full BRD v20.0 was integrated. In v5.0.0, Foundation chapters 02-04 were removed and all chapters renumbered.

Part III: Database (Chapters 06-09)

Complete data layer specification

Part IV: Backend (Chapters 10-13)

API and service layer implementation

Part V: Frontend (Chapters 14-17)

User interface specifications

Part VI: Implementation Guide (Chapters 18-23)

Step-by-step building instructions

Part VII: Operations (Chapters 24-28)

Deployment and ongoing maintenance

Part VIII: Reference (Chapters 29-32)

Quick lookup resources

Appendices

Book Statistics

MetricValue
Total Chapters32
Parts8
Appendices6 (A-F)
Database Tables54
API Endpoints75+
Domain Events80
Code Services142
Target GradeA (Production-Ready)

How to Print This Book

Use Pandoc to compile all chapters into a single PDF:

# Install Pandoc (if not installed)
# macOS: brew install pandoc
# Ubuntu: apt install pandoc texlive-xetex

# Navigate to Blueprint folder
cd /volume1/docker/planning/000-POS-Learning/00-Blue-Print

# Compile to PDF
pandoc \
  00-BOOK-INDEX.md \
  01-PREFACE.md \
  Part-I-Foundation/*.md \
  Part-II-Architecture/*.md \
  Part-III-Database/*.md \
  Part-IV-Backend/*.md \
  Part-V-Frontend/*.md \
  Part-VI-Implementation/*.md \
  Part-VII-Operations/*.md \
  Part-VIII-Reference/*.md \
  Appendices/*.md \
  -o POS-Blueprint-Book.pdf \
  --toc \
  --toc-depth=3 \
  --pdf-engine=xelatex \
  -V geometry:margin=1in \
  -V fontsize=11pt \
  -V mainfont="DejaVu Sans" \
  -V monofont="DejaVu Sans Mono"

Option 2: VS Code Extension

  1. Install “Markdown PDF” extension in VS Code
  2. Open each chapter
  3. Right-click > “Markdown PDF: Export (pdf)”
  4. Combine PDFs using any PDF merger

Option 3: Web-Based

Use online tools like:

  • Dillinger.io - Paste markdown, export as PDF
  • GitHub - Each .md file renders nicely for printing
  • Grip - Local GitHub-style markdown preview

Option 4: Build Script (Automated)

#!/bin/bash
# save as: build-book.sh

BOOK_DIR="/volume1/docker/planning/000-POS-Learning/00-Blue-Print"
OUTPUT="$BOOK_DIR/POS-Blueprint-Book.pdf"

# Collect all markdown files in order
FILES=(
  "$BOOK_DIR/00-BOOK-INDEX.md"
  "$BOOK_DIR/01-PREFACE.md"
)

# Add Part I-VIII
for part in Part-I-Foundation Part-II-Architecture Part-III-Database \
            Part-IV-Backend Part-V-Frontend Part-VI-Implementation \
            Part-VII-Operations Part-VIII-Reference Appendices; do
  for file in "$BOOK_DIR/$part"/*.md; do
    [ -f "$file" ] && FILES+=("$file")
  done
done

# Build PDF
pandoc "${FILES[@]}" -o "$OUTPUT" --toc --toc-depth=3

echo "Book compiled: $OUTPUT"

Estimated Print Size

FormatPagesNotes
Full Book~400-500All chapters and appendices
Core (Parts I-IV)~200Architecture + Backend
Quick Reference~50Part VIII only

Version History

VersionDateChanges
1.0.02025-12-29Initial Blueprint Book (39 chapters)
2.0.02026-02-19Expert panel review, integration module additions
5.1.02026-02-27Full review + enhancement of Parts III-V: fixed schema-per-tenant artifacts, added tenant_id to 38 tables, compound tax redesign, event_outbox + state_transitions tables, CQRS/MediatR for Sales, transactional outbox, 6-Gate Security Pyramid, ACL per provider, error code catalogue, SQLite schema rewrite, performance budgets, WCAG 2.1 AA accessibility, component state patterns
5.0.02026-02-25Removed Ch 02-04 (Foundation), rewritten Ch 01 as Blueprint Purpose, renumbered 35 to 32 chapters
3.0.02026-02-22Chapter consolidation (39 to 34): merged High-Level Architecture, Multi-Tenancy, Domain Model, Event Sourcing, and Offline-First into Architecture Characteristics (Ch 06) and Architecture Styles (Ch 07); full renumbering
3.1.02026-02-22Structural cleanup: section numbering standardized across all 34 chapters + 5 appendices, Ch 08/09 rewritten for RLS, Document Information footers added, cross-references audited and fixed
4.0.02026-02-25BRD v20.0 integrated as Chapter 08: Architecture Components; all subsequent chapters renumbered (+1); 26 contradictions reconciled across 12 chapters and 4 appendices
3.3.02026-02-25RFID Counting Subsystem: BRD v20 (Section 5.16 RFID Config, Section 4.6.8 multi-operator counting, 6 new decisions #108-113), schema fixes (tenant_id/RLS on all RFID tables, 3 new tables), chunked sync API, Raptag home dashboard + progress tracking + auto-save/recovery
3.2.02026-02-24Added Appendix F: BRD-to-Code Module Mapping (142 services across 7 modules, 80 domain events, 19 state machines, 107 decisions mapped with full traceability)

Contributors

RoleContributor
ArchitectClaude Code Architect Agent
AuthorClaude Code Editor Agent
ReviewerClaude Code Engineer Agent
ResearchClaude Code Researcher Agent
CoordinatorClaude Code Orchestrator

Blueprint Maintenance

How to Update This Blueprint

See BLUEPRINT-INSTRUCTIONS.md for complete maintenance procedures.

Quick Reference:

TaskAction
Edit contentUpdate master file, copy to mdbook-src/src/
Add chapterCreate file, update this index, update SUMMARY.md
Add appendixCreate file, update this index, update SUMMARY.md
Build PDFRun ./build-book.sh
Deploy webRun cd mdbook-src && mdbook build && wrangler pages deploy book

CRITICAL: When adding or removing chapters/appendices, you MUST update:

  1. This file (00-BOOK-INDEX.md)
  2. mdbook-src/src/SUMMARY.md
  3. Copy updated index to mdbook-src/src/00-BOOK-INDEX.md

Live Site

URL: https://pos-blueprint.pages.dev/

Thoughts & Recommendations

Current Status (as of 2026-02-22)

The blueprint is comprehensive and production-ready for Phase 3 implementation. Key observations:

Strengths

  • Complete database schema (51 tables across 13 domains)
  • Full API specification (75+ endpoints with request/response examples)
  • Multi-tenant architecture designed from day one
  • Offline-first design with conflict resolution strategies
  • 4-phase implementation roadmap with Claude Code commands
  • Consolidated architecture chapters with expert panel review and full implementation details

Areas for Future Enhancement

AreaRecommendationPriority
Testing StrategyAdd chapter on testing patterns (unit, integration, E2E)High
CI/CD PipelineAdd deployment automation chapterMedium
Performance BenchmarksAdd concrete performance targets and test plansMedium
Data Migration ScriptsAdd detailed QB POS to New POS migration scriptsHigh
Training MaterialsAdd end-user training documentationLow
Mobile ScreenshotsAdd actual Raptag UI screenshots to Appendix DLow

Implementation Notes

  1. Start with Phase 1 - Foundation is critical; don’t skip tenant isolation
  2. Use the code templates - Appendix E has copy-paste ready patterns
  3. Follow the ADRs - Chapter 05 documents why decisions were made
  4. Test offline early - Don’t leave offline mode for the end
  5. Schema provisioning - Use the SQL functions in Chapter 10

Open Questions

  • Payment processor final selection (Stripe vs Square vs both?)
  • RFID hardware vendor confirmation (Zebra confirmed?)
  • First pilot store selection for Phase 3 testing
  • Data retention policy for audit compliance

Change Log

DateChangeAuthor
2026-02-27v5.1.0 - Full review + enhancement of Parts III, IV, V (12 chapters)Claude Code
2025-12-29Initial Blueprint v1.0.0Claude Code
2026-01-24Added maintenance instructions, updated appendix listClaude Code
2026-02-22v3.0.0 - Chapter consolidation (39 to 34), full renumberingClaude Code
2026-02-23v3.1.0 - Structural cleanup: section numbering, RLS fix, footers, cross-refsClaude Code
2026-02-25v5.0.0 - Removed Ch 02-04 (Foundation), rewritten Ch 01 as Blueprint Purpose, renumbered 35 to 32 chaptersClaude Code
2026-02-25v4.0.0 - BRD v20.0 as Ch 08, full renumber (34 to 35 chapters), contradiction reconciliationClaude Code
2026-02-24v3.2.0 - Added Appendix F: BRD-to-Code Module MappingClaude Code

“Build it right the first time. This Blueprint is your guide.”