Code Documentation Index

This section is the engineering source of truth for the current implementation in salesarck_code.

It is intentionally code-first and commit-informed:

• Runtime behavior is documented from route, middleware, and service implementations.
• Domain contracts are documented from shared packages and schema files.
• Evolution notes are based on commit history, not assumptions.

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 and POS connection lifecycle.
• Square OAuth, webhook ingest, poll fallback, and wallet credit paths.
• Clover OAuth, webhook ingest, and payment normalization.
• Database schema, migration sequence, and invariants.
• Frontend routing and role-based UX gating.
• Email notification service (Resend-backed).
• 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 + transactional consistency.
• POS provider inputs are untrusted until signature verification and normalization complete.
• Documentation should be updated with implementation changes, not deferred to release time.