ADR-002: Frontend Monorepo Unification
ADR-002: Frontend Monorepo Unification
Status
Proposed — Pending engineering team review
Context
Two frontend repos serve the platform: peeq-mono (Angular 18.2/Nx 19.8, Tailwind/DaisyUI, fan-facing + mobile) and frontends (Angular 18.2/Nx 19.6, Bootstrap/Angular Material, admin + expert). Both call the same 24+ backend services with duplicated API gateway code. ~17% of frontend API calls target non-existent services.
Decision
Unify into a single Angular 18/Nx monorepo standardized on Tailwind CSS, executed in 4 phases.
Phases
- Shared component library — Create
@vzlabs/components, port high-usage components - CSS standardization — Migrate Bootstrap/Angular Material components to Tailwind equivalents
- Repo merge — Move frontends apps into peeq-mono Nx workspace
- Dead code removal — Remove 5 dead API gateways, reduce codebase by ~17%
CSS Framework Choice: Tailwind
| Criterion | Tailwind | Bootstrap |
|---|---|---|
| Already in use | peeq-mono (primary app) | frontends (admin/expert) |
| Flexibility | Utility-first, composable | Component-based, opinionated |
| Bundle size | Tree-shakeable | Full bundle unless customized |
| Ecosystem | DaisyUI, Headless UI | Angular Material |
| Migration effort | Less (larger codebase already uses it) | More (would require peeq-mono migration) |
Hypothesis Background
Primary: Frontend unification is feasible through CSS restyling, not logic rewrite (H4 L1). - Both repos are Angular 18, same framework version. - Same GraphQL backends, same auth (Keycloak), same chat (Stream). - Business logic in services is portable.
Alternative 1: Keep two repos, share code via published npm packages. - Rejected: Duplication continues; version drift between shared packages already observed.
Alternative 2: Rewrite all frontends in React/Next.js. - Rejected: Angular expertise exists, Angular 18 is current, no technical justification for framework switch.
Falsifiability Criteria
- If component migration takes >2x estimated effort for first 10 components → re-evaluate approach
- If Tailwind migration breaks >20% of existing peeq-mono styles → investigate DaisyUI compatibility
- If unified repo build time exceeds 15 minutes → split build configuration (per-app builds)
Evidence Quality
| Evidence | Assurance |
|---|---|
| Both repos Angular 18 | L2 (verified from package.json) |
| Same backend services | L1 (API gateway inventory) |
| CSS is primary blocker | L1 (H4) |
| Dead code (~17%) | L1 (API call analysis) |
Overall: L1
Bounded Validity
- Scope: peeq-mono and frontends repos; all 5 frontend apps
- Expiry: Re-evaluate if Angular drops LTS support or team decides to adopt a different framework
- Review trigger: If build times become unmanageable (>15 min) or team onboarding friction increases
Consequences
Positive: Single CI/CD pipeline, shared components eliminate duplication, consistent UX across all apps, easier to maintain. Negative: Large repo (800+ components combined), CSS migration is tedious, merge conflicts during transition. Mitigated by: Nx workspace structure isolates apps; component-by-component migration avoids big-bang risk.
Decision date: 2026-01-30 Review by: 2026-07-30