Code Documentation Index

This section documents the implementation that currently exists in salesarck-monorepo.

It is code-first:

• Runtime behavior is documented from route, middleware, and service implementations.
• Domain contracts are documented from shared packages and schema files.

Scope

The documentation in this section covers:

• Monorepo structure and package boundaries.
• API runtime and middleware execution order.
• Auth, tenant resolution, and RBAC authorization flow.
• Merchant onboarding, store-operator invitations, and POS connection lifecycle.
• Square OAuth, webhook ingest, poll fallback, and wallet credit paths.
• Clover OAuth, webhook ingest, payment polling, and payment normalization.
• Campaign creation, audience filtering, and cron-driven sending.
• Database schema, migration sequence, and invariants.
• Frontend routing and role-based UX gating.
• Email notification service.
• Observability, error handling, and operational controls.
• Deployment topology, environment contract, and quality gates.
• CI/CD pipelines and testing coverage.

Read This First

1. Repository Structure
2. Backend Runtime
3. Auth, Tenant, and RBAC
4. POS Integrations
5. Ingestion, Wallet, and Rewards

Full Map

• Repository Structure
• Backend Runtime
• Auth, Tenant, and RBAC
• Merchant Onboarding
• POS Integrations
• Ingestion, Wallet, and Rewards
• Email Notifications
• Data Model and Migrations
• Frontend Architecture
• Observability and Error Handling
• Deployment and Environments
• Testing and Quality
• Dependencies
• Git Evolution Timeline

Ground Rules

• Tenant context is server-derived and never trusted from client payloads.
• Reward and wallet state is treated as financial data: append-only ledger plus transactional consistency.
• POS provider inputs are untrusted until signature verification and normalization complete.
• Documentation should follow the code that exists today.