Platform architecture roadmap

This page summarizes docs/PLATFORM_STRATEGY_AND_ROADMAP.md (in the API repo, ~1400 lines, last updated 2026-09-21) rather than duplicating it. Read that document for full detail; this page exists so a new engineer understands why the core change freeze exists before running into it. It supersedes the older docs/ERP_MIGRATION_PLAN.md, which predates the storefront and the platform integrations work. Treat that one as history, not as a plan.

The problem, in one sentence

There is no single place that says what kind of business a tenant is, so nothing can be derived from it. Six separate mechanisms each hold a fragment of the answer (a business_type column on stores, 68 flat system_config booleans doing five unrelated jobs, a module registry that lists modules that don’t exist on disk, an entitlement system that connects to none of the above, ~25 frontend sidebar gate keys, and per-vertical conditionals). None of them agree with each other, and all of them are hand-edited per client, per store. A hotel, a production company, a cereals shop, and a repair shop are already live this way; a pharmacy is likely next. Each new vertical currently means a new pile of booleans and conditionals rather than reusing a decision already made for a previous one.

Where it’s headed

Business Type -> Template -> Capabilities -> Modules -> Configuration -> Permissions -> UI/workflows/channels

A business type becomes a template that declares which capabilities it composes. Capabilities are the runtime vocabulary everything else reads. Modules own their domains and talk to each other through events, not direct calls. A tenant declaring itself a restaurant should receive the modules, workflows, defaults, and storefront shape a restaurant needs, without a single new if (restaurant) conditional anywhere in Core, Sales, Inventory, POS, or Storefront. That’s the platform’s own acid test for whether this work succeeded (§10.1 of the full doc).

Sequencing

Twelve months is a directional horizon, not a commitment. Each phase is gated by an outcome, not a date, and ordinary client work runs alongside all of it.

1. Primitives (~months 1-2): the capability model and vocabulary, module registry reconciled with what’s actually on disk, domain event conventions, the migration framework skeleton, category hierarchy and shared property engine. First real migration: free-text brand fields into the existing brands table. Deliberately not in this phase: the stock migration, so the framework’s first real test isn’t also its hardest one.
2. Prove it on one vertical (~months 3-5): convert Retail end to end as the baseline, then Restaurant as the first genuinely different template, retiring the 46 isRestaurantMode branches as it goes. Gate: Restaurant runs on a different template over the same modules with zero restaurant conditionals left in Core, Sales, Inventory, or POS.
3. The risky migrations, on proven machinery (~months 5-8): the item framework migration, the stock migration, Accounting enabled as a controlled pilot on one or two tenants (dual-writing and reconciling against existing cash-flow reporting before any cutover). Fractional stock quantities, units separated from variants, lots/serialized units, bins.
4. Widening (~months 8-12+): booking/reservation engine, production costing, pharmacy batch/expiry scoping, CRM groundwork, device abstraction, capability-driven UI across remaining surfaces. This phase is a queue ordered by client demand, not a batch with a deadline.

What this means day to day

See Conventions for the actual rules (what’s paused vs. what continues as normal). The short version: bug fixes, performance, security, UX, reports, client config, and storefront content are all unrestricted. New features that touch Sales, Inventory/Stock, Costing, Items, Accounting, or Pricing, new modules, new system_config booleans, and new business_type conditionals are paused, not refused, they get classified and built as a capability wherever possible instead of a one-off conditional.

If you’re picking up Inventory work specifically: that module is both the largest in the codebase and the one most directly targeted by the Phase 1-3 inventory architecture work (policy model, fractional quantities, lots/bins) described above, so check the full roadmap doc before assuming the current shape is stable.