policy-ui/docs/CODEBASE_BUNDLE.md

# policy-ui — codebase bundle (for LLMs / handoff)

Single-document summary of the **policy-ui** Nuxt app: stack, API wiring, layout, main routes, composables, and data. Paste this into Perplexity, ChatGPT, or another tool when you need context without the full repo.

---

## Product intent (short)

Brokerage / agency management **workstation UI** (Central America / Colombia–oriented domain): quotes, sales pipeline, onboarding (solicitud, emissions), cartera (customers, policies, book), customer service (support, claims, collections, renewals), workstations, AI tools, settings. **Admin-first** structure; many areas use **mock data** until backends are connected.

---

## Stack

| Piece | Notes |
|--------|--------|
| **Nuxt** | `^4.3.1` (`compatibilityDate: 2026-02-25`) |
| **Vue** | `^3.5.28` |
| **@nuxt/ui** | `^4.5.0` (Nuxt UI 4) |
| **Tailwind** | `^4.2.1` (`app/assets/css/main.css`) |
| **nuxt-open-fetch** | `^0.13.8` — typed API clients from OpenAPI |
| **jspdf** | PDF generation |
| **zod** | validation |

**Scripts:** `dev`, `build`, `generate`, `preview`, `postinstall` → `nuxt prepare`.

**Dev server:** port **3737**, host `localhost` ([`nuxt.config.ts`](../nuxt.config.ts)).

---

## API clients (`nuxt-open-fetch`)

| Client | Base URL | Schema URL |
|--------|-----------|------------|
| `customer` | `http://localhost:4000/api/v1` | `http://localhost:4000/api/openapi` |
| `policy` | `http://localhost:4001/api/v1` | `http://localhost:4001/api/openapi` |
| `providers` | `http://localhost:4002/api/v1` | `http://localhost:4002/api/openapi` |
| `tasks` | `http://localhost:8080/api/v1` | `http://localhost:8080/openapi3.json` |

Usage: `useNuxtApp().$customer`, `$policy`, `$providers`, `$tasks` (generated from schemas when services run).

---

## Entry & layout

- [`app/app.vue`](../app/app.vue): wraps app in **`UApp`** → `NuxtLayout` → `NuxtPage`.
- Default layout [`app/layouts/default.vue`](../app/layouts/default.vue): **top bar** (`LayoutAppTopBar`), **collapsible sidebar** (Sales, Operations, optional Workstations/AI), main content area. Sidebar groups/feature flags via [`useSidebarFeatures`](../app/composables/useSidebarFeatures.ts) (localStorage: workstations, AI tools, leads hub).

---

## Directory map (`app/`)

| Path | Role |
|------|------|
| `pages/` | File-based routes (~73 Vue pages) |
| `components/` | UI including `layout/`, `quotes/`, etc. |
| `composables/` | Shared logic (~30 composables) |
| `layouts/` | `default.vue` shell |
| `assets/css/` | Global styles / Tailwind |
| `types/` | TS types (form catalog, quotes, branding, roles, …) |
| `data/` | JSON catalogs, mocks, seed data |
| `utils/` | Helpers (e.g. `useLocalStorageRef`) |
| `middleware/` | Route middleware if present |
| `plugins/` | Client/server plugins |

**Public:** `public/` including `public/forms/` for static PDF assets referenced by the forms catalog.

---

## Routes (by area)

Paths are under `app/pages/` unless noted.

- **Home / shell:** `/` (`index.vue` — large role-configurable dashboard), `home2.vue`, `calendar.vue`, `account.vue`
- **Quotes:** `/quotes` (mission-control style hub), `/quotes/mission-control`, `/quotes/new`, `/quotes/compare`, line flows: `/quotes/life`, `/quotes/health`, `/quotes/auto`, `/quotes/general-risk`, `/quotes/custom`
- **Sales / onboarding:** `/onboarding` (pipeline), `/sales/quick-lead`, `/sales/leads`, `/registration/client`, `/registration/policy`, `/onboarding/solicitud`, `/onboarding/emissions`, `/onboarding/policy-upload/new`, potential/active leads under `onboarding/`
- **Cartera:** `/customers`, `/customers/new`, `/customers/[id]`, `/policies`, `/policies/new`, `/policies/[id]`, `/policies/groups`, `/policies/book`, `/policies/app/[application_id]`
- **Customer service:** `/support`, `/support/[id]`, `/support/collectivos`, `/claims`, `/claims/[id]`, `/claims/intake/[token]` (standalone layout), `/claims/settings`, `/collections`, `/renewals`, `/renewals/[id]`
- **Workstation:** `/workstation/*` (collectivos, collections, claims, renewals, customer-service, facturacion)
- **AI tools:** `/ai-tools/*` (sales-factory, policy-comparator, email-writer, case-assistant)
- **Providers:** `/providers`, `/providers/new`, `/providers/[provider_id]`
- **Tasks:** `/tasks`, `/tasks/[id]`
- **Analysis:** `/analysis`
- **Settings:** `/settings` and children (organization, agents, providers, permissions, forms library, quote-requests, support-routing, customer-attention, profile-layouts, alerts, appearance, personalization, referral-channels)

Many pages set `definePageMeta({ ssr: false })` where client-only state or APIs are assumed.

---

## Composables (inventory)

| Composable | Purpose (brief) |
|------------|-----------------|
| `useAppShellLayout` | Sidebar collapse / layout |
| `useAppTheme` | Theme switching |
| `useBrokerageBranding` | Tenant branding in chrome |
| `useSidebarFeatures` | Toggle sidebar sections (workstations, AI, leads) |
| `useSuperAdmin` | Superadmin gate for org settings |
| `usePageTitle` | Document title |
| `useFormsCatalog` | Filter form catalog JSON, field groups, indexes |
| `useEmissionsQueue` | Local queue for emissions review |
| `useQuoteSession` | Comparative quote view model / session |
| `useSalesPipeline` | Deal pipeline stages for quote/onboarding flows |
| `useCustomerProfileVault` | Local profile / KYC-oriented draft |
| `usePdfFieldMappings` | PDF field mapping JSON |
| `useProviderContactEmails` | Carrier outbound email roles |
| `useClientRegistrationModel` / `usePolicyRegistrationModel` | Registration payloads |
| `useLifeQuoteDraft` / `useHealthQuoteDraft` / `useAutoQuoteDraft` | Line-specific quote drafts |
| `useDashboardHomeWidgets` | Home dashboard widgets + role presets |
| `useWelcomeDashboard` | Welcome KPIs / home content |
| `useSupportTickets` | Support ticket mock/state |
| `useCustomerAttention` | Customer attention tiers |
| `useProfileLayouts` | Profile section layouts |
| `useReferralChannels` | Referral sources |
| `useQuickLeads` | Quick lead capture |
| `useClientFavorites` | Starred clients |
| `useColectivos` | Collectivos data/helpers |
| `useAnalytics` | Analytics helpers |
| `useAlertConfig` | Alert configuration |
| `useQuoteRequestEmailEnabled` | Quote-request email toggle |

---

## Data & catalogs

- **`forms-catalog.json`** — PDF/form rows (insurer, sub-ramo, persona, paths).
- **`form-field-groups.json`** — Field groups linked to catalog matching.
- **`pdf-field-mappings.json`** — PDF field name mappings.
- **`taxonomy.ts`** — Slugs / taxonomy for routing.
- **`roles-seguros.ts`** — Seed roles for permissions UI.
- **Mocks:** `mock-customers`, `mock-claims`, `mock-support`, `mock-renewals`, `quotes-overview.mock`, `mock-analytics`, etc.

---

## Scripts (repo)

- [`scripts/import-forms.mjs`](../scripts/import-forms.mjs) — pipeline to generate/refresh form catalog from sources (when used).

---

## Conventions worth knowing

- **i18n:** UI copy is largely **English** in chrome; **Spanish** appears in some flows and labels; full translation is planned.
- **Mock vs API:** Several list views try API then fall back to mocks (e.g. policies); others are mock-only.
- **OpenAPI:** Clients expect **local** services on the ports above; without them, calls fail unless mocked.

---

## Files this bundle was generated from

- [`package.json`](../package.json)
- [`nuxt.config.ts`](../nuxt.config.ts)
- Glob: `app/pages`, `app/composables`, `app/types`, `app/data`

Regenerate or extend this file when architecture changes significantly.