Chapter 01: Blueprint Purpose

1.1 What This Book Is

The POS Platform Blueprint is the complete architecture and implementation guide for building an enterprise multi-tenant retail Point of Sale system. It is the single source of truth for every design decision, database schema, API contract, deployment procedure, and implementation pattern needed to build the platform from scratch.

This book is self-contained. Every diagram, code sample, and specification lives within these chapters. There are no external dependencies or unresolved references. A development team should be able to build the entire system using only this document.

1.2 Who Uses This Book

This Blueprint is designed for Claude Code teams and agents during the coding and development phase. It serves as the foundation plan that AI-assisted development teams follow when implementing the POS platform.

1.3 What the POS Platform Does

The POS Platform is a unified commerce solution for small-to-mid-size retailers operating both online and brick-and-mortar stores. It replaces legacy point-of-sale systems with a modern, multi-tenant SaaS platform.

Core Capabilities

Key Architecture Decisions

• Event-Driven Modular Monolith (Central API) + Microkernel (Nexus POS)
• PostgreSQL with Row-Level Security for tenant isolation
• Online-first with offline fallback — API-primary data access via React Query, 2-table SQLite fallback for brief outages (ADR-048)
• Node.js/TypeScript backend, React/TypeScript single web application (Nexus POS), React Native mobile (Nexus Raptag)
• PostgreSQL LISTEN/NOTIFY for v1.0 events (Kafka deferred to v2.0)

1.4 How to Use This Book

Structure: 9 Chapters, 3 Parts, 2 Appendices

Appendix F provides BRD-to-code module mapping (142 services, 80 events, full traceability). Appendix G provides the Application Screen Reference (118 screens, 13 wireframes, full BRD-to-UI traceability).

Reading Guide

Starting a new implementation? Read Parts I-II first for context, then jump to Part III for database design.

Implementing a specific module? Start with Ch 05 (Architecture Components / BRD) to find your module’s requirements, then check Ch 04 (Architecture Styles) for implementation patterns.

Looking up architecture patterns? Ch 04 contains the full implementation reference (~5,000 lines) including online-first with offline fallback, multi-tenancy, security, testing, and observability strategies.

1.5 Key Mega-References

Two chapters serve as the primary implementation references and contain the bulk of the technical detail:

Chapter 04: Architecture Styles Analysis (~5,000 lines)

The architectural backbone of the system. Key sections include:

Chapter 05: Architecture Components / BRD v20.0 (~19,900 lines)

The complete Business Requirements Document with 7 modules and 113 decisions:

Authority rule: When the BRD (Ch 05) conflicts with any other chapter, the BRD wins.

1.6 Conventions Used in This Book

• Section numbering: All chapters use ## X.Y Title format (e.g., ## 1.1 What This Book Is)
• Cross-references: Point to chapter numbers and filenames (e.g., “See Chapter 04”)
• Code samples: Complete, copy-paste ready; file paths included as comments
• Document footer: Every chapter ends with a standardized Document Information table
• Dual-file sync: Every chapter exists in both the master directory and mdbook-src/src/ for web publishing

1.7 Summary

This Blueprint Book is the complete specification for the POS Platform. It is designed to be consumed by Claude Code agents and development teams who will implement the system. Start with the architecture chapters (Part II) for the big picture, then drill into the specific Part relevant to your current task.

Next Chapter: Chapter 02: Architecture Decision Records

Document Information

This chapter is part of the POS Blueprint Book. All content is self-contained.