How walid85us/tmpos2026 works
1. This repo is a TypeScript monorepo-style application centered on a React/Vite frontend plus a Node server. The product is a multi-tenant platform/admin console with separate owner, tenant, shipping, and backend-control-plane experiences.
2. The frontend entry path is src/main.tsx → src/App.tsx, then into layout and feature shells under src/layouts, src/components, src/owner, src/tenant, src/shipping, and src/backend-control-plane. The UI is split by role and workflow, not by a single generic page model.
3. Access control is a first-class boundary in the client. src/context/AccessContext.tsx, src/components/AccessGuard.tsx, LockedFeature, PendingApproval, NotProvisioned, and the various auth/session helpers gate routes and features based on tenant, role, and entitlement state.
4. Authentication and session state flow through a dedicated auth layer in src/auth and src/pilot. The client-side auth stack includes Supabase-aware session bootstrap/bridge logic, while server/platform-identity provides server-side session resolution, verified identity lookup, and authorization enforcement. The repo also contains “shadow” and “live” authz diagnostics, which suggests the system compares client expectations with server truth during rollout.
5. The core backend domain is server/platform-identity. It contains database access, migrations, seeds, authorization repository/resolver code, permission cataloging, protected-action checks, audit-event writing, and identity-link provisioning. This is the authoritative boundary for platform identity, RBAC, and auditability.
6. Persistent state and schema evolution are handled explicitly through SQL migrations in server/platform-identity/migrations and seed scripts in server/platform-identity/seeds, with utility scripts for Supabase migrations and identity validation under scripts/. This repo treats schema, bootstrap data, and authz contracts as part of the architecture, not just deployment detail.
7. The backend control plane is its own subsystem. src/backend-control-plane provides a read-only UI shell and card-based readiness views, while server/bcp-pilot provides the corresponding read models and route registration logic. The data flow here is “server-generated readiness model” → “client dashboard/coverage cards,” intended for operational verification rather than end-user business transactions.
8. Shipping is a distinct domain with both client and server pieces. src/shipping contains provider registry, carrier scorecards, automation engine, and carrier locators, while server/adapters contains integrations for EasyPost, Shippo, and ShipStation. This is the clearest external-API boundary in the repo, and should be drawn as a provider abstraction layer behind shipping workflows.
9. The product surface is broad and role-specific: owner/admin pages cover domains, plans, billing, permissions, team management, provisioning, support tools, and platform settings; tenant pages cover employee access, roles, and security settings; shipping pages cover batch labels, automation, carrier analytics, and provider management. These are all client-side feature areas backed by shared access/session infrastructure rather than separate apps.
10. The docs/ tree is operational architecture documentation, not incidental prose. It contains phase plans, decision records, QA/evidence packages, access inventory, and a dev-test-data registry template/checklist system. For diagramming, treat this as the repo’s governance and rollout control plane.
11. knowledge-work-plugins/ is a separate plugin/skill catalog with .claude-plugin, MCP manifests, and many domain packs. It looks like tooling/content for AI-assisted workflows rather than runtime application code, so it should be shown as an adjacent support layer, not inside the product execution path.
12. Net flow: the browser loads the React app, auth/session state establishes role and tenant context, access guards select the correct shell, domain modules render business operations, and specialized backend services handle identity, authorization, audit, control-plane readiness, and carrier/provider integrations.
Main entry points: App.tsx App · platform-identity Platform identity · layouts Shell layouts · scripts Diagnostics
Components 18
Client app
React/Vite frontend organized by auth, layouts, role shells, and domain features.
- main · Vite entry that mounts the React app.
src/main.tsx - App · Top-level application composition and route selection.
src/App.tsx - Access layer · Client access context and guards for tenant, role, and entitlement state.
src/context/AccessContext.tsx - Auth stack · Supabase-aware bootstrap, token bridging, and app-session mapping.
src/auth - Pilot client · Pilot and diagnostic clients for session resolve and identity checks.
src/pilot - Shell layouts · Role-based chrome and navigation boundaries for owner and tenant experiences.
src/layouts - Owner console · Owner/admin workflows for domains, plans, billing, permissions, provisioning, support, and settings.
src/owner - Tenant console · Tenant-facing employee, role, access, and security management pages.
src/tenant - Shipping UI · Shipping workflows for labels, automation, analytics, providers, and locators.
src/shipping - Control plane UI · Backend control-plane shell with readiness cards and exposure views.
src/backend-control-plane
Server runtime
Node services for identity, control-plane read models, and carrier/provider adapters.
- Platform identity · Server authority for sessions, authorization, permissions, protected actions, audit, and identity links.
server/platform-identity - BCP pilot · Server-side readiness/read-model pipeline and route registration for the control plane.
server/bcp-pilot - Carrier adapters · Provider adapters for EasyPost, Shippo, and ShipStation behind shipping workflows.
server/adapters - Migrations · Platform identity schema evolution and authorization/audit foundations.
server/platform-identity/migrations - Seed data · Development bootstrap and rollback seed scripts for identity and authorization setup.
server/platform-identity/seeds
Governance
Docs, diagnostics, and rollout controls that define architecture and verification.
- Docs · Operational architecture, decision records, milestones, evidence packages, and registry templates.
docs - Diagnostics · Repository diagnostics and migration helpers for auth, authorization, Supabase, and schema checks.
scripts
Support plugins
Adjacent knowledge-work plugin catalog used for assisted workflows, not product execution.
- Knowledge plugins · Adjacent plugin and skill catalog for AI-assisted workflows and domain knowledge.
knowledge-work-plugins
Connections 21
- main → App: boots · Browser entry mounts the application root.
- App → Access layer: guards · Route and feature visibility are gated by access state.
- App → Auth stack: hydrates · Application session state is built from auth bootstrap and token bridge logic.
- App → Shell layouts: selects · Owner and tenant shells are chosen by role and workflow.
- Shell layouts → Owner console: renders · Owner layout hosts admin and platform management pages.
- Shell layouts → Tenant console: renders · Tenant layout hosts tenant administration pages.
- App → Shipping UI: routes · Shipping workflows are exposed as a dedicated client domain.
- App → Control plane UI: routes · Control-plane dashboard is a separate client experience.
- Auth stack → Pilot client: observes · Pilot clients and diagnostics validate session resolution and identity behavior.
- Pilot client → Platform identity: verifies · Client diagnostics compare expected session state with server authority.
- Access layer → Platform identity: enforces · Authorization decisions depend on server-derived identity and permissions.
- Platform identity → Migrations: evolves · Identity and authorization contracts are backed by explicit SQL migrations.
- Platform identity → Seed data: bootstraps · Dev identity and platform-owner data are seeded from SQL scripts.
- Platform identity → Diagnostics: validated by · Diagnostics exercise authorization, session resolve, and migration boundaries.
- Control plane UI → BCP pilot: reads · Read-only UI is fed by server-generated readiness models.
- Shipping UI → Carrier adapters: delegates · Shipping workflows defer carrier-specific work to provider adapters.
- Docs → Platform identity: governs · Milestones and decision records define identity and authorization rollout.
- Docs → BCP pilot: governs · Control-plane readiness phases are documented and verified through docs.
- Diagnostics → Auth stack: checks · Diagnostics include Supabase, session bootstrap, and auth-provider inventory checks.
- Diagnostics → Shipping UI: checks · Shipping-specific diagnostics validate carrier and entitlement behavior.
- Knowledge plugins → Docs: adjacent · Plugin catalog supports knowledge workflows and documentation adjacent to runtime code.