Skip to content
Chewbills User Guide

Architecture Overview

System map

Chewbills is split into a React frontend, a Node/Express backend, and this Astro Starlight documentation site. Key components:

  • Frontend (frontend/) — React 18 + React Router, Tailwind, React Query, Chart.js.
  • Backend (backend/) — Express APIs, Postgres, AI-provider routing, PDF/OCR pipelines.
  • Docs (docs/) — Astro + Starlight, fed by userguide.md to keep persona workflows synchronized.

Supporting scripts:

  • scripts/sync-readme-docs.js copies persona sections from userguide.md into these MDX files.
  • npm run docs:* helper commands build/run the docs locally and in CI.

See README.md for full architecture diagrams and deployment references.

Authorization and module governance

Section titled “Authorization and module governance”

Backend guard model

Section titled “Backend guard model”

Module routes should be protected with layered guards:

  1. requireModule('<module-key>') for organization-level module enablement.
  2. requireModuleAccess('<module-key>') for role-level module visibility/access.
  3. requirePermission('<module-key>', '<action>') for action-level authorization.

This keeps feature enablement, module access, and operation permissions separate and explicit.

Frontend guard model

Section titled “Frontend guard model”

Frontend module routes and navigation should align with backend authorization:

  1. requiredFeature: '<module-key>' for feature toggle behavior.
  2. Role-aware module checks (hasModuleAccess) for UI visibility.
  3. Permission-aware UI affordances for action-level controls.

Default role requirement (strict)

Section titled “Default role requirement (strict)”

Membership assignment paths are strict:

  • Organizations must have a configured default role (core.organization_roles.is_default = true).
  • If missing, user creation, invite acceptance, and SSO JIT membership assignment fail with DEFAULT_ORG_ROLE_REQUIRED (HTTP 422 in API flows).

Recommended validation query:

SELECT organization_id, COUNT(*) AS default_roles
FROM core.organization_roles
WHERE is_default = TRUE
GROUP BY organization_id
HAVING COUNT(*) <> 1;

New module onboarding expectations

Section titled “New module onboarding expectations”

When introducing a new module:

  1. Add module actions to shared/permissions.ts (PERMISSION_CATALOG).
  2. Ensure platform-admin role management UI exposes module access and actions.
  3. Add backend route guards (requireModule, requireModuleAccess, requirePermission).
  4. Add frontend route/nav gating (requiredFeature, hasModuleAccess).
  5. Update architecture and checklist docs (architecture.md, docs/NEW_MODULE_CHECKLIST.md, docs/MODULE_DEVELOPMENT_GUIDE.md).