Pharus Architecture
Pharus is a platform. This document describes its architecture as a stack of layers, each with a clear responsibility and contract. The intent is to keep the layers genuinely separate so the platform can support multiple use cases (CPG manufacturing, dropshipping, distribution, etc.) and allow tenant-defined customization, without forking the foundation each time.
This overview describes the destination shape — Pharus at full scale.
Architecture Overview
Pharus is structured as five layers. Each layer depends only on the layer below it, and each one has its own contract, its own evolution lifecycle, and its own discipline.
Layer 5 — Clients. Visualization and interaction surfaces: web app, mobile app, desktop app, CLI, AI agents (MCP, A2A, …), and partner integrations (Slack, EDI, accounting, BI, …). All clients consume the same public API — no privileged path to lower layers — and the architecture treats first-party and third-party clients identically.
Layer 4 — User-facing API. The stable, public contract — operations, reads, and events — that clients consume. Implemented as per-domain microservices behind load balancers; the surface a tenant sees reflects its variant (which endpoints exist) plus its extensions (additional or overridden behavior). Layer 4 reflects Layer 3 (what's allowed), not Layer 2 (what's possible), and is conservative by design — once exposed, endpoints age forever.
Layer 3 — Business Logic. The opinionated rule sets that turn permissive components into a usable product, organized as variant templates per vertical (CPG manufacturing, dropshipping, distribution, …). Each variant ships with a baseline template every tenant on that variant uses, and tenants can optionally layer their own extensions on top — overriding rules, adding validations, customizing workflows — without touching the variant or other tenants. Whether a tenant uses extensions, and who writes them, is a packaging concern, not an architectural one.
Layer 2 — Domain Components. Mechanically permissive primitives, exposed as stateless, org-agnostic microservices — one per domain (Platform, Purchase Order, Work Order, Sales Order, Materials Inventory, Finished Goods Inventory). Each scales horizontally with multiple instances behind a load balancer, and operates on whatever connection Layer 1 hands it — a component has no notion of which tenant it serves beyond the connection itself. Components define what is structurally possible; they encode no product rules.
Layer 1 — Data. Where state lives. One database per organization, distributed across multiple Postgres instances — smaller orgs share an instance, larger orgs run on dedicated ones — plus a separate platform instance holding the tenant catalog and cross-tenant data (users, auth, membership). Every instance is replicated (primary + replica) for reliability. Layer 1's contract upward is simple: given a tenant identifier, return a connection to that tenant's database.
The key separation is between Layer 2 (what's possible) and Layer 3 (what's allowed). Components are infrastructure; business logic is product. This split is what makes variants and tenant programmability achievable without forking the foundation.