Roadmap (Phase 0 → Phase 39)

Dependency order, not calendar order — a solo/small team should follow this sequence because each phase consumes the previous ones. See docs/phase-plan/phase-0-3-build-plan.md for the detailed near-term plan; this doc is the full-picture reference.

Phase	Name	Depends on	What it builds
0	Architecture & Standards	—	This scaffold: monorepo, conventions, DB/API/event standards
1	Platform Foundation	0	api-gateway, auth-service, event bus
2	Merchant Infrastructure	1	merchant-service, API keys, webhooks, org/RBAC
3	Identity Federation	2	seller-identity-service, sequential email/phone OTP linking — replaced by an OAuth account-linking handshake in Phase 28, see item 22
4	Listing Exchange	3	listing-service, catalog-service, media-service, listing visibility modes
5	Search	4	search-service (OpenSearch), directory-service
6	Trade Value Engine	4, 5	trade-engine, currency normalization
7	Matching Engine	6	matching-engine, recommendation-service, Trade Compatibility Score
8	Offer Network	7	offer-service, offer ranking/limits
9	Trade Session Engine	8	trade-session-service — the canonical state machine, most important service in the system
10	Checkout Orchestration	9	checkout-service, payment-status-service, merchant checkout adapters (Shopify first)
11	Notifications	9	notification-service — email/SMS/push/webhook/in-app
12	Compliance & Fraud	all above	moderation-service, fraud-service, reputation-service
13	Analytics	all above	analytics-service — GMV, trade volume, match rate, completion rate
14	Developer Platform	core APIs	docs-site, sandbox-service
15	SDK Platform	14	sdk-js/sdk-typescript (done in Phase 0-3), then React/Next/Vue/RN/Flutter/iOS/Android/Java/.NET/Python/PHP
16	Widget Platform	15	trade-button, offer-modal, trade-inbox, trade-card, trade-directory, trade-status, checkout-redirect
17	Ecommerce Plugins	16	Shopify (scaffolded now) → WooCommerce → Magento → BigCommerce
18	Merchant Dashboard	13, 15	apps/merchant-dashboard full build-out
19	Internal Operations Console	all above	apps/ops-console — approvals, fraud, moderation, feature flags
20	TBBN Exchange	all previous phases	apps/exchange-web — the reference implementation, built last on purpose
21	Advanced Exchange Intelligence	20	AI matching, ring/multi-hop trades, bundle trades, trade credits
22	Business Profile Foundation	2	business-service, apps/business-dashboard — Business/Branch models, Business↔Merchant linking, direct self-registration (reverses Phase 3's federation-only identity creation — see conflict-resolution-log.md item 18)
23	TBBN Space	22	Space as an independent bookable product (usable beyond TBBN trades), real payment/payout/commission mechanics
24	Ratings & Reviews	22, 23	User-submitted reviews of Merchants and Space branches, rolling up to the Business
25	Consolidated Business Billing	22, 23	Move the Stripe customer relationship from Merchant to Business; per-aspect line-item invoice sections
26	Individual Listings + Peer-to-Peer Trade Completion	3, 22	Listing.merchantId becomes optional, POST v1/listings/individual, the SCHEDULING_<side>/EXCHANGE_<side>_CONFIRMED/EXCHANGE_FAILED state machine (TBBN_Flow.docx §8.2) — see conflict-resolution-log.md items 19 and 24
27	Headless Sellers	26	Seller.userId nullable again, Merchant.headlessSellersAllowed, POST merchant/sellers/headless — a merchant on a high-enough tier can complete a barter trade for a trade participant with no TBBN account at all — see item 21
28	OAuth Account-Linking Handshake	27	Replaces Phase 3's sequential email/phone OTP linking entirely — OAuthClient/OAuthAuthorizationCode, services/seller-identity-service/src/oauth-link/, services/merchant-service/src/oauth-clients/ — see item 22
29	Domain Consolidation	28	apps/exchange-web becomes the app serving root tbbnetwork.com (sign up/sign in only ever there); apps/marketing-site retired, 3 sections folded into exchange-web; new apps/account-dashboard (account.tbbnetwork.com — payments, subscriptions, account-linking); cross-subdomain return_to + httpOnly refresh-token cookie — see item 23
30	Checkout-Orchestration Scoping	26, 29	Listing.listingType gates whether an Offer can even be made; a SALE-only listing renders as a Google-Merchant-style outbound link (merchantItemUrl) on exchange-web instead of an OfferBuilder — see item 24
31	TBBN Space Selection & Negotiation	26	packages/core-geo (Haversine), GET v1/branches/nearby-spaces (200-mile default radius), Listing.preferredSpaceBranchId, TradeSpaceProposal (counter-propose/accept), wiring SpaceBooking.tradeSessionId for real — see item 25
32	TBBN Space as an API Platform	31	"Calendly for space" — SpaceApiKey/SpaceApiKeyConfig (Business-rooted, not Merchant), GET v1/space/search (global, unbounded unless asked, distinct from Phase 31's 200-mile nearbySpaces), headless (API-driven) bookings on behalf of a client with no TBBN account, hosted payment/confirm links — see item 26
33	Developer Docs Consolidation	32	doc(s).tbbnetwork.com → developer.tbbnetwork.com, split into real /merchant/docs and /space/docs path sections — see item 27
34	Space Rooms, Verification, Visibility & Business Webhooks	32	Space (the actual bookable room within a Branch, replacing Branch as the booking unit), Business.verificationStatus gating Space creation, per-Space visibility (PUBLIC/API_ONLY/RESTRICTED_EMAIL), configurable headless-booking consent (SpaceApiKeyConfig.consentMode), BusinessUser/BusinessUserRole (Business-side RBAC), BusinessWebhookSubscription/Delivery (Business-rooted outbound webhooks), BusinessOneTimeCharge/PlatformFeeSchedule (data-model-only free-listing fee) — see item 28
35	admin.tbbnetwork.com	34	Planned, not built — a real TBBN_OPS staff-auth principal, Business verification review, PlatformFeeSchedule management, dead-lettered webhook replay across both Merchant and Business webhook tables; supersedes ops-console's ad-hoc unauthenticated convention — see item 28
36	"Airbnb for Space" categorization + tbbnetwork.com landing page	34	Space.category/checkInMethod (browsable "Airbnb for Space" fields layered on Phase 34's Calendly-style booking mechanics), fixed a real packages/sdk-typescript gap (no space passthrough at all, blocking server-side Space fetches), renamed space-dashboard's /browse to /listings, new SpaceListingsTeaser on exchange-web's home page, and marketing-site's 4 orphaned pages (how-it-works/solutions/pricing/company) finally migrated into exchange-web — see item 29

Why TBBN Exchange (Phase 20) is nearly last

It is the first customer of everything built in Phases 1-19, not a separate product with its own shortcuts. Building it early means building against a moving target and duplicating logic that belongs in the shared services. See docs/business/business-model.md.

Current status vs. what's still ahead

Phases 0-20 are done: every services/* and packages/* folder through Phase 17 has real business logic against the shared Postgres schema (not just a runnable skeleton), and all six apps/* are wired to those real APIs (Phase 18-20) — merchant-dashboard, exchange-web, and ops-console fetch live data with no hand-authored placeholder data left; marketing-site, docs-site, and status-page are static/content-only by design, not unfinished. The 7 non-JS SDKs (part of Phase 15) are real idiomatic source but explicitly flagged untested, since no toolchain for those 7 languages exists in this environment.

Phase 21 (Advanced Exchange Intelligence) is the only phase from the original Phase 0-21 plan not built, by explicit decision, not oversight. Phases 22-25 are built: Phase 22 (business-service, apps/business-dashboard, direct self-registration — see docs/business/conflict-resolution-log.md item 18), Phase 23 (space-service, apps/space-dashboard — TBBN Space, standalone this pass, see item 19), Phase 24 (Reviews, added to reputation-service), and Phase 25 (Business-rooted billing — BusinessSubscription, see item 20).

Phases 26-31 are built, per a founder-directed course correction reversing part of Phase 22 (merchant-mediated Seller creation) — see docs/business/conflict-resolution-log.md items 21-25: Phase 26 (individual listings + peer-to-peer trade completion — the exact gap flagged when Phase 23 shipped, item 19), Phase 27 (headless Sellers), Phase 28 (OAuth account-linking, replacing Phase 3's OTP flow), Phase 29 (domain consolidation — exchange-web now serves root tbbnetwork.com; new apps/account-dashboard), Phase 30 (checkout-orchestration scoping), and Phase 31 (TBBN Space selection/negotiation, finally wiring SpaceBooking.tradeSessionId).

Phases 32-33 are built, per a follow-up founder directive turning TBBN Space into its own API platform — see items 26-27: Phase 32 (SpaceApiKey/SpaceApiKeyConfig, global GET v1/space/search distinct from Phase 31's 200-mile marketplace radius, headless bookings on behalf of a client with no TBBN account via a hosted payment/confirm link) and Phase 33 (developer.tbbnetwork.com, split into /merchant/docs and /space/docs).

Phase 34 is built, per a second follow-up founder directive turning Space into a real room-booking platform — see item 28: Branch is no longer the bookable unit — a new Space model (a room within a Branch) now owns pricing and bookings, each with its own hours/capacity/ photos/notes/visibility; Business.verificationStatus blocks Space creation until TBBN verifies the Business (interim review lives in ops-console, unauthenticated, same convention as every other "ops-only in practice" endpoint until Phase 35 exists); a headless booking's consent-vs- straight flow is now configurable per SpaceApiKeyConfig; BusinessUser/BusinessUserRole give a Business real team roles (mirroring MerchantUser) instead of just a single owner; and a new Business-rooted outbound webhook mechanism (reusing the existing HMAC signing/retry kernel) lets a Business receive Space booking lifecycle events. The founder's requested free-listing fee is real and DB-driven (PlatformFeeSchedule/BusinessOneTimeCharge) but not yet collected or admin-editable — both wait on Phase 35. Phase 35 (admin.tbbnetwork.com) is explicitly planned but not built this pass — see item 28's own note and docs/security/rbac-strategy.md's TBBN_OPS gap.

Phase 36 is built, per a third follow-up founder directive — see item 29: Space gains a purely browsable category (study room, meeting room, restaurant table, retail corner, etc.) and checkInMethod (numbered/signage/staff-assisted) so a restaurant or small-corner host fits the same model as a formal room — "Airbnb for Space" layered on Phase 34's "Calendly for Space" mechanics, with no change to booking mechanics. Fixed a real gap found while wiring this up: packages/sdk-typescript had no space passthrough at all, silently blocking any Next.js Server Component (e.g. apps/exchange-web) from fetching Space data server-side. space-dashboard's /browse is renamed /listings; exchange-web's home page gained a real SpaceListingsTeaser section (live Space cards + cross-domain filter links into space.tbbnetwork.com/listings); and marketing-site's 4 pages that were never actually migrated during Phase 29's domain consolidation (how-it-works/solutions/pricing/company) are now real exchange-web routes.

Phase 37 is built, per a fourth follow-up founder directive — see item 30: apps/exchange-web is renamed apps/Landing-page, and the home page is split in two. The home page now carries a lightweight Hero (a real provided photo, a single "Trade Now" CTA) and a single-row TopTradingItems teaser — no search/filter/sort of its own. The full BrowseGrid that used to live under the old hero moved wholesale to a new /marketplace route; nav/footer "Browse" links now point there. Everything below the teaser (AudienceSplit/HowItWorks/SpaceListingsTeaser/ SpaceExplainer/SafetyTips, Phase 36's Space-side landing content) is unchanged.

Phase 38 is built, per a fifth follow-up founder directive — see item 31: apps/marketing-site is deleted entirely (everything real had already migrated out by Phase 36). Landing-page's Hero becomes a 2-slide carousel (Trade, then Space) with no text between the nav and the hero; its SpaceListingsTeaser drops its search form/category filters for a TopTradingItems-shaped single row. space-dashboard (space.tbbnetwork.com) is rebuilt into a Space-only marketing page — its session-gated home moved from / to /dashboard; a new /get-started resolver routes a visitor to tbbnetwork.com login, business.tbbnetwork.com, a Space-enabling Branch page, the existing Space-onboarding form, or their own dashboard, whichever actually applies. This also fixed a real pre-existing gap: space-dashboard had its own duplicate login instead of deferring to tbbnetwork.com like every other subdomain (account-dashboard's cross-subdomain cookie pattern is now shared by both).

Phase 39 is built, per a sixth follow-up founder directive — see item 32: a root .env.example catalogues every AWS/Google Maps/Stripe credential this system will need once its Console/Local adapter stand-ins are swapped for real ones (not done this phase). TBBN_OPS real staff auth ships — admin.tbbnetwork.com (apps/ops-console) gets a working 2-step OTP login, a real session gate, and OpsRolesGuard-enforced guards on every ops-only backend endpoint (7 found, one more than originally scoped: space-service's commission-rate override). No new StaffUser table — staff are User rows with authType: TBBN_OPS + a new staffRole field, provisioned only via tools/create-staff-user, never a public endpoint. merchant-dashboard/business-dashboard get real marketing homes at / (their session-gated dashboards moved to /dashboard); business-dashboard's local login — a genuine violation of the tbbnetwork.com-only sign-in rule, confirmed by reading its actual OTP calls — is replaced with the same cross-subdomain cookie pattern space-dashboard got in Phase 38 (merchant-dashboard's own login was verified legitimate and left untouched — merchant reps are a distinct principal kind). A new BehaviorEvent model plus two recommendation-service "for-visitor" endpoints add real (cold-start-safe, never fabricated) personalization to both the trade marketplace and Space listings, gated behind a new cookie-consent system (primary/essential vs. secondary/analytics, with a preferences modal) built for Landing-page and space-dashboard. A separate location-consent prompt feeds real coordinates into space-service's existing lat/lng search params.

See docs/architecture/service-catalog.md for the exact status of every individual folder — it can occasionally lag a beat behind reality after a fast round of edits; trust the source over the table if they conflict, and fix the table in the same change.