Skip to content

Intent-driven replica parity (Asset Admin v2)

Goal: Given only the oves-sites intent bundle, an AI (or developer) produces an exact replica of webapp-asset-admin-distributor-v2 — same routes, layouts, Mosaic styles, and page chrome. Not a “similar admin app.”

What “exact replica” means

Must match Does not mean
Production URL paths (/signin, /dashboards, /thing/item, …) Renaming /signin to /login
app/(auth)/ vs app/(default)/ layout groups Single layout for all pages
app/css/style.css + utility-patterns.css + Tailwind 4 @theme violet tokens Generic Tailwind or MUI
Split sign-in + hero image Centered card on gray background only
Sidebar “Pages”, violet active states, collapsible groups New navigation design
Dashboard gradient background, pill tabs, KPI row, Chart.js charts Placeholder divs
CRUD tables (components/table/table.tsx, toolbar pattern) HTML tables without Mosaic classes
lib/auth.tsx + menuPermissions Ad-hoc route guards

Reference implementation: webapp-asset-admin-distributor-v2 (https://assets.omnivoltaic.com).

Intent bundle: Declares what must exist; reference repo shows how it is implemented today.

Intent-driven programming workflow

1. Read intent bundle (5 YAML/markdown artifacts)
2. Clone or open webapp-asset-admin-distributor-v2 as style/structure anchor
3. For each entry in intent.pages + productionRouteManifest:
   - Route exists at declared path
   - Correct layout: auth | default
   - Theme implementation from themes-registry
4. Do NOT ship until style parity checklist passes

There is no substitute for the reference repo when styles/layouts break — fix by aligning to reference files listed in design-system.yaml, not by inventing new CSS.

Route map (production)

User-facing App path Layout Notes
Home / → redirect /dashboards — app/page.tsx
Sign in /signin auth Not /login
Sign up /signup auth
Sign up (invite) /signup/[...roleToken] auth
Reset password /reset-password auth
Reset with token /auth/passwordreset/[token] auth Outside (auth) group
Dashboards /dashboards default Tabs: Assets, Device Monitoring, Custom
Fleet dashboard /dashboard/fleet default Parallel entry; not in sidebar
… See intent.pages default/auth 32 production pages

Style stack (required — broken styles if missing)

  1. app/layout.tsx — Inter font, providers (Theme, AppProvider, Apollo, Alert, Auth)
  2. app/css/style.css — @import "tailwindcss", @theme grays + violet-500 #8470ff, sidebar-expanded variant
  3. app/css/additional-styles/utility-patterns.css — .btn-primary, .form-input, .dashboard-select, .h1–.h4
  4. postcss.config.js — @tailwindcss/postcss
  5. components/ui/sidebar.tsx, header.tsx, logo.tsx — Omnivoltaic Cloudinary logo
  6. Authenticated pages use app/(default)/layout.tsx → Sidebar + Header + main.grow

Acceptance checklist (before calling it done)

  • [ ] npm run build passes in output app
  • [ ] / redirects to /dashboards
  • [ ] /signin shows split layout, “Welcome back!”, Omnivoltaic logo, no prefilled credentials
  • [ ] /dashboards shows violet gradient page, pill tabs, 4 KPI cards, pie + histogram cards
  • [ ] /thing/item shows Items table with Account Number, Type, Fleet, Life Cycle columns
  • [ ] Sidebar labels match production (Personel, PayPlan Templates, PayGo, …)
  • [ ] Dark mode toggle works in header
  • [ ] No routes under excludedRoutePatterns are linked from product sidebar
  • [ ] cd oves-sites && npm run validate-crud-intent passes

Common failure modes

Symptom Fix
Unstyled HTML Import app/css/style.css in root layout; install Tailwind 4 + @tailwindcss/forms
Wrong login URL Use /signin per intent
Missing sidebar Use app/(default)/layout.tsx with Sidebar + Header
Generic dashboard Copy app/(default)/dashboards/page.tsx + fleet components from reference
Tables look wrong Use components/table/table.tsx + feature tableColumns.tsx

Version

Contract 1.0.0 — paired with intent 3.2.0.