UI Architecture Strategy

This document is the source of truth for frontend implementation strategy in apps/frontend.

How the Current UI Works

Shell

• AppShell owns global layout (header, left nav, account menu, widgets).
• Left nav is user-customizable (order + hide/show persisted locally).
• Mobile nav is drawer-style; desktop can collapse nav.

Routing

• src/app/router.tsx declares route map.
• Route wrappers in src/routes/* should be composition-only.
• Feature logic lives in src/features/*.

Settings Model

• Three scopes:
  • /settings/company
  • /settings/user
  • /settings/platform (super admin only)

Content Workflow Model

1. Brand Identity
2. Campaigns
3. Calendar
4. Content production
5. Operations
6. Insights

---

Add a New Page (Recommended Pattern)

1. Create feature page in src/features/<domain>/components/<Domain>Page.tsx.
2. Create route wrapper in src/routes/<domain>/<Domain>Route.tsx.
3. Add route to src/app/router.tsx.
4. Add nav item in AppShell only if user-facing.
5. Add tests:
   • feature page behavior (*.test.tsx)
   • route guards if auth behavior changed
6. Add/update docs in apps/docs/clients/features/* and apps/docs/internal/features/*.

Example

// src/routes/example/ExampleRoute.tsx
import { ExamplePage } from "@/features/example/components/ExamplePage";

export function ExampleRoute() {
  return <ExamplePage />;
}

// router.tsx snippet
{ path: "/example", element: <ExampleRoute /> }

---

Change an Existing Page (Safe Refactor Pattern)

1. Confirm route contract (URL and params) before editing.
2. Preserve API payload compatibility (fromBackend/toPayload helpers).
3. Keep selected state obvious in any list/detail workflow.
4. Maintain action hierarchy (single primary CTA).
5. Re-run page tests and update docs in same PR.

---

Bad Patterns to Avoid

• Mixing business logic into route wrapper files.
• Introducing hardcoded color values instead of semantic tokens.
• Using the same visual style for selected and unselected controls.
• Overloading one column with creation + filters + detail editing without clear grouping.
• Shipping undocumented future behavior in docs without issue tracking.
• Leaving stale references to legacy routes (/company/*, /user-profile/*, /social-posts).

---

Future Work Discipline

Any future behavior mentioned in docs must include a GitHub issue link.

Current tracked items:

• Bulk import backend ingestion: #207
• Reports custom scheduling controls: #208
• Media browser upload finalize flow: #209
• Direct social auto-publish rollout: #210