Imported from everythingparlays/overboard-b2b-documentation (AGENTS.md). Install upstream with npx skills add everythingparlays/overboard-b2b-documentation. Copyright stays with the author.

OverBoard Sports B2B — Documentation & Specs

Package Overview

This repo is documentation-only — no runtime code. It's the source of truth for the OBS B2B platform (a multi-tenant, white-labeled fan-engagement bingo game licensed to sports teams). It drives AI-assisted and human development against two implementation repos: overboard-b2b-template (frontend) and overboard_sports_backend (backend API + Lambda workers + AWS CDK infra).

Read This First

1. documents/POC-baseline/README.md — Current implementation was built as a fast POC, not against specs. Read this before assuming any existing pattern is intentional or should be preserved as-is.
2. documents/PRD/OBS_B2B_Platform_PRD.md — The product requirements source of truth. Requirement IDs (e.g. TEN-03, SEC-08) are stable references used throughout specs. [V1] = build now, [FUTURE] = don't build but don't foreclose, [CONSTRAINT] = a rule shaping how V1 is built.

Standards Hierarchy

Do NOT read all specs upfront. Select the relevant spec for the task at hand.

Webapp Specs (spec/webapp/)

(Not yet written — see documents/POC-baseline/webapp.md for current-state notes in the meantime.)

Backend Specs (spec/backend/)

(Not yet written — see documents/POC-baseline/backend.md for current-state notes in the meantime.)

Workers Specs (spec/workers/)

Lambda evaluators (board/prop evaluation, prize workers). Not yet written — see documents/POC-baseline/workers.md.

Infra Specs (spec/infra/)

An architecture.spec.md covering the rest of the CDK stack (VPC/ECS/ALB/SQS/Lambda topology) hasn't been written yet — see documents/POC-baseline/infra.md for current-state notes in the meantime.

Core Module Specs (spec/core-modules/)

Cross-cutting capabilities used across webapp, backend, and workers — most importantly auth/tenancy (Clerk + multi-tenant resolution) and shared data models. See documents/HLDs/data-access-isolation.md (requirements) and spec/core-modules/2-approved/mongodb-access-isolation.spec.md (implementation — exact collection names, Atlas custom roles, CDK constructs) before writing any code that touches non-B2B collections (BetEvent, Prop, Entity) or that scopes B2B service/developer credentials. B2B now has one shared dependency: obs-b2b-shared — types, the Zod HTTP contract, and Mongoose models — vendored in four places (frontend, node-server, lambdas, prize-worker). pb-shared-deps and core were removed from the B2B repos entirely (pb-shared-deps still serves the D2C products; core was absorbed into the frontend). Layering rules — notably that interfaces/ must stay Mongoose-free so the frontend can import it — are in documents/HLDs/b2b-shared-deps.md. See documents/POC-baseline/README.md for detail. These should be specced early since drift here propagates everywhere. Only read specs in 3-active/ (or 2-approved/ if implementing something not yet built) for implementation.

Feature Specs (spec/features/)

Per-feature behavior. Only read specs in 2-approved/ or 3-active/ for implementation. Feature specs should cite the PRD requirement IDs they implement.

Key Constraints

1. The current codebase is a POC, not a spec-compliant target. Don't treat existing patterns as correct by default — check whether a layer/concern spec exists and covers it first. See documents/POC-baseline/.
2. Prefer configuration over per-tenant code (PRD TEN-C1) — except set-once branding (BRAND-01) and per-sponsor prize fulfillment logic (PRIZE-05), which are explicit exceptions.
3. Security and reliability are first-class, not deferred. This effort exists specifically to take the platform from POC to production-grade (PRD Section 13 Security, Section 14 Observability). Flag gaps against those sections as they're found.
4. Requirement IDs are stable. When writing specs, tickets, or tests, reference PRD IDs (e.g. OPT-04) rather than re-describing the requirement.
5. Never generate changes inside the obs-b2b-shared submodule directory — it is one repo vendored in four places; edits go through that repo, then all four pins move together. And never suggest connecting to or running scripts against the production MongoDB database (it also serves the live D2C mobile app — see known-issues.md). If a task seems to require either, stop and flag it instead of proceeding — see SETUP.md for the full contributor-boundaries list this applies to.

Related Repositories