Architecture

Athas Boilerplate is designed as a modular starter where transport, provider, and product slices can evolve independently without changing core application rules.

Layer model

Backend

• apps/backend/src/modules/*: domain-oriented modules.
• application: use cases and orchestration.
• infrastructure: provider SDK adapters, repositories, external APIs.
• interface: transport adapters (oRPC, HTTP/OpenAPI, webhook handlers).

Frontend

• apps/*/src/routes: route adapters only.
• apps/*/src/features/<feature>: feature-local API hooks, screen orchestrators, and presentational components.
• libs/shared-api: typed client wiring and transport glue.

Shared packages

• libs/contracts: contract-first schemas and oRPC contract router.
• libs/shared-api: client utilities using ContractRouterClient.
• libs/rbac-capabilities: capability constants only (no business logic).

API architecture

• oRPC is primary for first-party apps (admin, client, future mobile).
• HTTP/OpenAPI remains available for third-party integration and webhooks.
• Audience projections are explicit at contract level:
  • public
  • client
  • admin

Detailed policy: /docs/audience-projections.

Contract-first default

1. Define contract schemas in libs/contracts.
2. Expose contract router via @orpc/contract.
3. Implement backend router with implement(contract).router(...).
4. Consume contract types in frontend via shared typed client.

This follows oRPC contract-first guidance and keeps DTO drift low.

Boundary rules (non-negotiable)

• Provider SDK calls stay inside infrastructure adapters only.
• Routes do not execute transport logic directly.
• Role/capability checks stay in adapter guards/middleware.
• Business ownership and invariants stay in application/domain use cases.

Module composition

• Soft-disable exists today via environment flags.
• Hard-remove packaging is being implemented through module profiles and scaffolding workflows.
• See /docs/module-profiles for the active profile model.

Execution docs

• Commerce delivery sequence: /docs/commerce-sprint-plan.
• Foundation migration and handoff: /docs/foundation-closeout.

Related architecture pages

• /docs/backend-patterns
• /docs/frontend-patterns
• /docs/api-interfaces
• /docs/modular-composition