# 🏛️ Fastapp Engine — Arquitetura

> Documento vivo. Atualizado para refletir o motor **Anti-Gravity** e a **Sovereign Navigation Architecture**.

---

## Visão Geral

O **Fastapp Engine** é uma fábrica de aplicações. O motor genérico (Core) interpreta definições JSON e renderiza CRUD, formulários, tabelas e navegação automaticamente. Seguimos uma abordagem de **Escada de Abstração** (Core L1, L2, L3) para garantir que a complexidade seja tratada pelo motor, e não pela customização.

### 📚 Dimensões de Documentação
- [🛰️ **Diretrizes Anti-Gravity**](./ANTIGRAVITY_GUIDELINES.md): O Norte e as Leis de Abstração.
- [🏛️ **Hierarquia e Metadados**](./APP_HIERARCHY.md): Estrutura de App, Module, Object e Property.
- [🧬 **Taxonomia de Dados**](./DATA_TAXONOMY.md): A semântica que governa o comportamento.
- [🔌 **Protocolo Fadap**](./FADAP_PROTOCOL.md): Sincronização entre Metadados e Storage.
- [🔄 **Sistema de Workflow**](./WORKFLOW_SYSTEM.md): Manual técnico de fluxos Human-Led.
- [🧭 **Sistema de Tutoriais**](./TUTORIAL_SYSTEM.md): Onboarding interativo com Driver.js.
- [📱 **WAHA Integration**](./WAHA_INTEGRATION.md): Camada de infraestrutura para WhatsApp (envio + webhook).
- [📣 **Sistema de Comunicados**](./COMUNICADO_SYSTEM.md): Painel de regras de notificacao por evento (e-mail + WhatsApp).

```mermaid
graph TB
    subgraph "A Fábrica (Fastapp Engine)"
        SEED["🌱 Seed / Builder"]
        SNAPSHOT["📸 Snapshot"]
        API["🔌 API Dinâmica v1"]
        CORE["⚙️ Core Components"]
        STORE["🗃️ System Store"]
    end

    subgraph "Modelo 01 (CRM Flux)"
        CRM_PAGES["📊 Dashboard + Kanban"]
        CRM_COMPS["🧩 Lead Components"]
        CRM_STORE["💾 Lead Store + Offline"]
    end

    subgraph "Modelo 02...N (Futuro)"
        FUTURE["🎫 Helpdesk, 📦 Inventário..."]
    end

    SEED --> SNAPSHOT --> STORE
    SEED --> API
    STORE --> CORE
    API --> CORE
    CORE --> CRM_PAGES
    CORE --> FUTURE
    CRM_COMPS --> CRM_PAGES
    CRM_STORE --> CRM_PAGES

    style SEED fill:#dc2626,color:#fff
    style CORE fill:#4338ca,color:#fff
    style API fill:#059669,color:#fff
    style SNAPSHOT fill:#7c3aed,color:#fff
```

---

## Stack

| Camada | Tecnologia | Versão |
|--------|-----------|--------|
| Framework | Nuxt 4 | `^4.3.1` |
| UI Components | PrimeVue (Aura) | `^4.5.4` |
| CSS | Tailwind CSS 3 + CSS custom properties | `^3.4.19` |
| State (Global / UI) | Pinia (`system.ts`) | `^0.11.3` |
| State (Data L3) | Pinia (`appData.ts`) | **SWR + Request Coalescing** |
| Utilities | VueUse (`@vueuse/nuxt`) | `^14.2.1` |
| Forms | VeeValidate + Zod | `^4.15.1` / `^3.25.76` |
| Drag & Drop | vuedraggable | `^4.0.1` |
| Realtime | Socket.IO (client + server) | `^4.8.3` |
| ORM | Prisma | `^6.2.1` |
| DB | PostgreSQL (Supabase) | — |

---

## Hierarquia: App → Module → Object → Property

```mermaid
erDiagram
    APP ||--o{ MODULE : "contains"
    APP ||--o{ OBJECT : "defines"
    MODULE ||--o{ OBJECT_REF : "references"
    OBJECT ||--|{ PROPERTY : "has"
    APP {
        string name
        string slug
        boolean is_active
        boolean is_frozen
    }
    OBJECT {
        string name
        string label
        string type
        string crud_mode
        string key_property
        string label_property
    }
    PROPERTY {
        string name
        string label
        string type
        string content_type
        boolean required
        boolean show_in_list
        boolean show_in_form
    }
```

---

## Taxonomia Semântica de Objetos

Cada object no Fastapp é classificado por **3 eixos** independentes:

### 1. Categoria Semântica (`object.category`)

Define o "comportamento de vida" do dado no ecossistema:

| Categoria | Descrição | Exemplo | Impacto no Gerador |
|-----------|-----------|---------|-------------------|
| `master` | Dado mestre, estável, base para outros | Broker, AssetClass, User | Caches, dropdowns globais, busca por nome |
| `transactional` | Eventos, registros de fluxo, alta volatilidade | Transaction, Lead, UserAsset | Índices por data, logs de auditoria, filtros de período |
| `configuration` | Parâmetros do sistema ou do usuário | AppSettings, WalletProfile | Interfaces simplificadas ("Settings Page") |

### 2. Natureza Arquitetural (`object.nature`)

Define **onde** o dado mora fisicamente:

| Natureza | Armazenamento | Comportamento |
|----------|--------------|---------------|
| `physical` | Tabela própria no DB | ID único global, referenciável por qualquer um |
| `embedded` | Dentro do JSON do pai | Sem tabela própria; morre se o pai for deletado |
| `virtual` | Calculado em runtime | Agregações (ex: total_balance do usuário) |

### 3. Relacionamentos (`object.relations[]`)

**Tipos de Vínculo:**

| `relation.type` | Semântica | Exemplo |
|-----------------|-----------|---------|
| `belongs_to` | Referência a um master ou pai | UserAsset → Broker |
| `has_one` | Propriedade de um filho único | User → WalletProfile |
| `has_many` | Propriedade de uma coleção | WalletProfile → UserAsset[] |
| `associates_with` | Relação N:N | Tag ↔ Lead |

**Estratégias de Persistência:**

| `relation.storage` | Como se salva | Quando usar |
|---------------------|---------------|-------------|
| `reference_id` | Salva apenas o ID (FK relacional) | Dados independentes |
| `document_embed` | Salva o objeto inteiro no JSON | Dados acoplados ao pai |
| `pivot` | Tabela intermediária | Relação N:N |

### Matriz Category × Nature

```mermaid
graph TD
    subgraph "master"
        M_P["physical<br/>Broker, AssetClass<br/>Tabela própria"]
        M_E["embedded<br/>—<br/>(raro)"]
        M_V["virtual<br/>—<br/>(raro)"]
    end

    subgraph "transactional"
        T_P["physical<br/>Lead, UserAsset<br/>Tabela c/ índices"]
        T_E["embedded<br/>Transaction<br/>JSON no pai"]
        T_V["virtual<br/>TotalBalance<br/>Calculado"]
    end

    subgraph "configuration"
        C_P["physical<br/>WalletProfile<br/>Tabela simples"]
        C_E["embedded<br/>AppSettings<br/>JSON no App"]
        C_V["virtual<br/>—<br/>(raro)"]
    end

    style M_P fill:#059669,color:#fff
    style T_P fill:#2563eb,color:#fff
    style T_E fill:#7c3aed,color:#fff
    style T_V fill:#d97706,color:#fff
    style C_P fill:#64748b,color:#fff
```

### Exemplo Concreto: App Gestão de Ativos

```mermaid
erDiagram
    BROKER ||--o{ USER_ASSET : "belongs_to (reference_id)"
    ASSET_CLASS ||--o{ USER_ASSET : "belongs_to (reference_id)"
    USER_ASSET ||--|{ TRANSACTION : "has_many (document_embed)"
    WALLET_PROFILE ||--o{ USER_ASSET : "has_many (reference_id)"

    BROKER {
        string name
        string cnpj
        category master
        nature physical
    }
    ASSET_CLASS {
        string name
        enum risk_level
        category master
        nature physical
    }
    USER_ASSET {
        string ticker
        number quantity
        number avg_price
        category transactional
        nature physical
    }
    TRANSACTION {
        date date
        enum type
        number quantity
        number price
        category transactional
        nature embedded
    }
    WALLET_PROFILE {
        string name
        number target_conservative
        category configuration
        nature physical
    }
```


---

## Meta-API & Gestão de Sistema

Além do CRUD de dados (`/api/v1/data`), o Fastapp expõe endpoints de gestão para evoluir a própria estrutura do sistema em tempo de execução.

### 1. Snapshot (`POST /api/system/snapshot`)
- **Função**: Gera uma "foto" estática do estado atual do banco (Apps, Objetos, Campos) em `app/fastapp/static-manifest.ts`.
- **Uso**: Freeze de versão para produção ou backup de schema.

### 2. Schema Evolution (`PATCH /api/app/:id`)
- **Função**: Permite alterar definições de objetos (adicionar campos, mudar layout) via API.
- **Uso**: Editores visuais (Builder) ou scripts de migração (ex: `apply-layout-grid.ts`).

### 3. Storage Adaptation (`POST /api/data/:object/storage`) [Planejado]
- **Função**: Analisa a definição do objeto e executa DDL (Create/Alter Table) para alinhar o banco físico.
- **Uso**: Transformar um objeto "Generic" (JSON) em "Native" (Tabela SQL) para performance, sem reiniciar o servidor.

### 4. Admin Portal (Ferramentas de Gestão)
- **Schema Manager**: Interface visual para editar Apps e Objetos (`PATCH /api/app`). Alavanca componentes dinâmicos para editar a si mesmo.
- **API Tester**: "Mini Postman" integrado para testar endpoints do sistema (`/api/v1/data`) e validar respostas.
- **AI Laboratory 🧪**: Versão evoluída do Agent Playground. Permite simular personas, gerir blueprints temporários (Laboratory Manifesto) e persistir contextos de análise LLM no LocalStorage.

### 5. Custom Pages & Dynamic Routing
- **Configuração**: O manifesto suporta uma lista de `pages`.
- **Roteamento**: 
    - `page.type === 'custom'`: Aponta para um arquivo físico em `pages/`.
    - `page.type === 'dynamic_crud'`: Gera automaticamente a rota para o objeto.
- **Visibilidade**: O `AppMenu.vue` resolve essas rotas dinamicamente para o sidebar.

---

## Fluxo de Runtime — Onde vive a inteligência

```mermaid
sequenceDiagram
    participant URL as Browser URL
    participant Page as Dynamic Page
    participant Store as System Store
    participant Static as static-manifest.ts
    participant API as /api/app (GET)
    participant DataAPI as /api/v1/data/:object
    participant DynDB as dynamic-db.ts
    participant NativeModel as Prisma Model (Lead)
    participant RecordTable as Record Table (Generic)

    URL->>Page: /crm/crm/lead
    Page->>Store: fetchDefs()
    Page->>AppData: fetchObjectData('lead') - non-blocking SWR
    
    Note over AppData: Checking for pending promises...
    alt Already fetching (Request Coalescing)
        AppData-->>Page: await the same existing promise ✓
    else Not in cache
        AppData->>DataAPI: GET /api/v1/data/lead?$limit=100
        DataAPI-->>AppData: Data[]
        AppData-->>Page: Hydrated data ✓
    end

    alt is_static (Snapshot ativo)
        Store->>Static: import StaticManifest
        Static-->>Store: App[] (instantâneo)
    else is_live (Dev / sem snapshot)
        Store->>API: GET /api/app
        API-->>Store: App[] (do banco)
    end

    Store-->>Page: objectSchema resolved
    Page->>DataAPI: GET /api/v1/data/lead

    DataAPI->>DynDB: isNativeModel("lead")?

    alt Modelo nativo existe
        DynDB->>NativeModel: prisma.lead.findMany()
        NativeModel-->>DataAPI: Lead[]
    else Modelo genérico (ex: tarefa)
        DynDB->>RecordTable: prisma.record.findMany(object_name)
        RecordTable-->>DataAPI: Record[] → flatten JSON
    end

    DataAPI-->>Page: data[]
```

---

## API Dinâmica v1

### Endpoints

| Rota | Método | Descrição |
|------|--------|-----------|
| `/api/v1/data/:object` | GET | Lista (com filtros e ordenação via query params) |
| `/api/v1/data/:object` | POST | Cria (com validação meta-driven) |
| `/api/v1/data/:object/:id` | GET | Busca por ID |
| `/api/v1/data/:object/:id` | PATCH | Atualiza (com validação) |
| `/api/v1/data/:object/:id` | DELETE | Remove |

### Estratégia Híbrida: Native vs Generic

```mermaid
graph LR
    REQ["Request /api/v1/data/:object"]
    META["meta-validation.ts<br/>Resolve properties do manifest"]
    DYN["dynamic-db.ts<br/>isNativeModel?"]

    subgraph "Caminho A: Native"
        PRISMA["prisma.lead / prisma.app<br/>Model dedicado"]
    end

    subgraph "Caminho B: Generic"
        RECORD["prisma.record<br/>data: Json + object_name"]
        FLATTEN["Flatten: {id, ...data, timestamps}"]
    end

    REQ --> META --> DYN
    DYN -->|"lead, app"| PRISMA
    DYN -->|"tarefa, contato, ..."| RECORD --> FLATTEN

    style PRISMA fill:#059669,color:#fff
    style RECORD fill:#7c3aed,color:#fff
```

- **Native**: objetos com model Prisma dedicado (`lead`, `app`). Performance máxima.
- **Generic**: objetos criados no Builder. Usam tabela `Record` com `data Json`. Zero setup.

### Validação Meta-Driven

```mermaid
graph TD
    BODY["Request Body"] --> RESOLVE["resolveObjectProperties(name)"]
    RESOLVE --> VALIDATE["validateBody(body, properties)"]
    VALIDATE -->|"required fields"| CHECK_REQ["Campos obrigatórios presentes?"]
    VALIDATE -->|"type checking"| CHECK_TYPE["string/number/boolean correto?"]
    CHECK_REQ -->|"❌"| ERR400["400: Validation failed"]
    CHECK_TYPE -->|"❌"| ERR400
    VALIDATE -->|"✓"| CLEAN["cleanBody(body, properties)"]
    CLEAN -->|"strip _tabId, unknowns"| SAVE["Save to DB"]

    style ERR400 fill:#dc2626,color:#fff
    style SAVE fill:#059669,color:#fff
```

### Filtragem & Ordenação (URL-Driven)

A API aceita filtros e ordenação via query params. O frontend usa a URL como **fonte única de verdade**.

**Query Parser** (`server/utils/query-parser.ts`):

O motor agora prioriza o formato **Flattened** para query strings, facilitando a integração com APIs externas.

| Operador | Formato Flat (Soberano) | Formato Legado (Legacy) | Descrição |
|----------|----------------|----------------|-----------|
| `=` | `?campo=valor` | `?filters[campo][=]=valor` | Igualdade simples |
| `ne` | `?campo[ne]=valor` | `?filters[campo][$ne]=valor` | Diferente |
| `gt` / `gte` | `?campo[gt]=5` | `?filters[campo][$gt]=5` | Maior que / Maior ou igual |
| `lt` / `lte` | `?campo[lt]=10` | `?filters[campo][$lte]=10` | Menor que / Menor ou igual |
| `like` | `?campo[like]=mario`| `?filters[campo][$like]=mario` | Busca textual (Case Insensitive) |
| `between`| `?campo[between]=a,b`| `?filters[campo][between]=a,b` | Intervalo de valores |

**Paginação e Ordenação Soberana:**

| Parâmetro | Tipo | Descrição | Exemplo |
|-----------|------|-----------|---------|
| `$limit` | `number` | Quantidade de registros por página | `?$limit=50` |
| `$skip` | `number` | Quantidade de registros a pular | `?$skip=100` |
| `$sort[f]`| `1 / -1`| Ordenação (1=ASC, -1=DESC) | `?$sort[name]=1` |
| `granularity`| `string`| Resolução temporal para BI | `?granularity=week` |

**Coerção automática**: `"true"` → `boolean`, `"42"` → `number`, `"null"` → `null`.

**Fluxo URL-Driven:**

```mermaid
sequenceDiagram
    participant User as Usuário
    participant Filter as CoreDynamicFilter
    participant URL as URL (query params)
    participant Page as index.vue
    participant API as /api/v1/data/:object
    participant Table as CoreDynamicTable

    Note over Filter: onMounted → readFromUrl()
    User->>Filter: Seleciona campo, operador, valor
    Filter->>URL: router.replace({ query })
    URL->>Page: watch(route.query) dispara
    Page->>API: GET /api/v1/data/lead?filters[status][=]=NOVO
    API-->>Page: data[] filtrado
    Page->>Table: :data="data"
    Note over URL: URL bookmarkável e compartilhável
```

- **Native models**: filtros viram cláusula `where` do Prisma (performático)
- **Generic records**: filtros aplicados in-memory após fetch (JSON field)

---

## Sistema de Snapshot

```mermaid
sequenceDiagram
    participant Admin as Admin Panel
    participant API as POST /api/system/snapshot
    participant DB as PostgreSQL
    participant FS as Filesystem
    participant Store as System Store

    Admin->>API: Clique "Gerar Snapshot"
    API->>DB: prisma.app.findMany()
    DB-->>API: App[] (com modules/objects JSON)
    API->>FS: writeFileSync(static-manifest.ts)
    FS-->>API: Arquivo gerado
    API-->>Admin: Toast "Snapshot gerado!"

    Note over Store: No próximo boot (produção):
    Store->>FS: import StaticManifest
    Note over Store: is_static = true, sem DB
```

### Smart Store — Prioridade de Dados

| Condição | Fonte | `is_static` |
|----------|-------|-----------|
| `StaticManifest.length > 0` + produção | Arquivo estático | `true` |
| Dev mode (`import.meta.dev`) | API `/api/app` | `false` |
| API falha + manifest existe | Arquivo estático (fallback) | `true` |
| Nenhum manifest + API ok | API `/api/app` | `false` |

### `is_frozen` no App

Cada App pode ter `is_frozen: true`. Quando congelado, o sistema ignora a API e usa exclusivamente o arquivo estático — simulando produção "compilada".

---

## Componentes Core

```mermaid
graph TD
    subgraph "Navegação Soberana"
        HUB["CoreBuilderHub<br/>Top bar contextual"]
        MENU["CoreAppMenu<br/>Sidebar colapsável"]
    end

    subgraph "Orquestração"
        CRUD["CoreDynamicCRUD<br/>mode: modal|page|inline"]
    end

    subgraph "Visualização"
        TABLE["CoreDynamicTable<br/>columns via show_in_list"]
        LIST["CoreDynamicList<br/>edição in-place"]
    end

    subgraph "Filtros"
        FILTER["CoreDynamicFilter<br/>URL-driven, adaptive inputs"]
    end

    subgraph "Formulário"
        FORM["CoreDynamicForm<br/>VeeValidate + Zod runtime"]
        FIELDS["CoreDynamicFields<br/>recursivo, layout vertical|inline"]
        RENDERER["CoreFieldRenderer<br/>type → PrimeVue"]
    end

    subgraph "Ferramentas do Arquiteto"
        ARCHITECT["FastApp Architect<br/>Schema Studio v3"]
        FLOW["FastApp Flow<br/>Visual Metadata Explorer"]
        AGENT["FastApp Agent<br/>Enterprise AI Copilot"]
    end

    HUB -->|contexto builder| ARCHITECT & FLOW & AGENT
    MENU -->|contexto navegação| CRUD
    CRUD --> TABLE & LIST
    CRUD -->|Dialog| FORM
    FORM --> FIELDS
    FIELDS -->|inner_collection| FIELDS
    FIELDS --> RENDERER

    style CRUD fill:#4338ca,color:#fff
    style FORM fill:#059669,color:#fff
    style HUB fill:#0a0d14,color:#e2e8f0,stroke:#4338ca
    style ARCHITECT fill:#6366f1,color:#fff
    style FLOW fill:#2563eb,color:#fff
    style AGENT fill:#7c3aed,color:#fff
```

### Props & Eventos

| Componente | Props | Eventos |
|-----------|-------|---------|
| `CoreDynamicCRUD` | `schema`, `data`, `mode`, `objectName` | `create`, `update`, `delete`, `edit-click` |
| `CoreDynamicTable` | `schema`, `data` | `edit`, `delete` |
| `CoreDynamicList` | `schema`, `data`, `editable` | `edit`, `delete`, `update` |
| `CoreDynamicForm` | `properties`, `initialValues` | `submit` |
| `CoreDynamicFields` | `properties`, `values`, `errors`, `prefix`, `setFieldValue`, `layout` | — |
| `CoreFieldRenderer` | `property`, `modelValue` | `update:modelValue` |

### CRUD Modes

| Modo | Criar | Editar | View Default |
|------|-------|--------|-------------|
| `modal` | Dialog | Dialog | Table |
| `page` | `/create` | `/[id]` | Table |
| `inline` | Dialog | In-place na lista | List |

---

## Banco de Dados

```prisma
model App {
  id          Int      @id @default(autoincrement())
  name        String
  slug        String   @unique
  description String?
  version     String   @default("1.0.0")
  icon        String   @default("pi pi-box")
  is_active   Boolean  @default(true)
  is_frozen   Boolean  @default(false)
  created_at  DateTime @default(now())
  modules     Json     @default("[]")
  objects     Json     @default("[]")
}

model Lead {
  id       Int    @id @default(autoincrement())
  nome     String
  email    String
  whatsapp String
  status   String @default("NOVO")
  ordem    Int    @default(0)
}

model Record {
  id          Int      @id @default(autoincrement())
  object_name String
  data        Json     @default("{}")
  created_at  DateTime @default(now())
  updated_at  DateTime @updatedAt
  @@index([object_name])
}
```

**Lead** = model nativo (performance). **Record** = tabela genérica para objetos dinâmicos.

---

## Estrutura de Diretórios

```
lead-nuxt/
├── app/
│   ├── components/
│   │   ├── core/                    # ⚙️ Motor dinâmico
│   │   │   ├── BuilderHub.vue       # 🔧 Top bar contextual (Sovereign Nav)
│   │   │   ├── AppMenu.vue          # 📁 Sidebar colapsável (route-driven)
│   │   │   ├── DynamicCRUD.vue      # Orquestrador (modal/page/inline)
│   │   │   ├── DynamicFilter.vue    # 🔍 Filtro universal (URL-driven)
│   │   │   ├── DynamicTable.vue     # DataTable por metadados
│   │   │   ├── DynamicList.vue      # List view com inline editing
│   │   │   ├── DynamicForm.vue      # Zod runtime + VeeValidate (recursivo)
│   │   │   ├── DynamicFields.vue    # Recursivo (inner_collection, Ontology v3)
│   │   │   ├── FieldRenderer.vue    # type → PrimeVue component
│   │   │   ├── AssetUpload.vue      # Upload para semantic: asset
│   │   │   └── MapRenderer.vue      # Mapa L2 (spatial_type: point)
│   │   ├── fastapp/                 # 🏗️ Ferramentas do Arquiteto
│   │   │   ├── AgentChat.vue        # Chat streaming com AI Architect
│   │   │   ├── FastNode.vue         # Node customizado para Vue Flow
│   │   │   ├── PropertyListEditor   # Editor visual de propriedades
│   │   │   └── SchemaPropertyMgr    # Manager de schemas v3
│   │   ├── crm/                     # 📊 Custom: CRM Flux
│   │   ├── sosplantao/              # 🏥 Custom: SosPlantão
│   │   ├── central-filtros/         # 🏭 Custom: Central Filtros
│   │   └── lead/                    # 👤 Custom: Lead (Arquétipo)
│   ├── layouts/
│   │   └── default.vue              # Shell: BuilderHub + Sidebar + Content
│   ├── pages/
│   │   ├── fastapp/
│   │   │   ├── apps.vue             # Gerenciador + Snapshot
│   │   │   ├── schema-v3.vue        # 🏗️ FastApp Architect (3-pane)
│   │   │   ├── diagram.vue          # 🗺️ FastApp Flow (Vue Flow)
│   │   │   └── agent.vue            # 🤖 FastApp Agent (AI Copilot)
│   │   ├── [app]/
│   │   │   ├── index.vue            # App Dashboard
│   │   │   ├── [module]/index.vue   # Module Dashboard (Focal)
│   │   │   └── [module]/[object]/   # 🔄 Rotas dinâmicas
│   │   └── crm/                     # Custom pages
│   ├── fastapp/
│   │   ├── manifest.ts              # Types: App, Module, Object, Property
│   │   └── static-manifest.ts       # 📸 Snapshot (auto-gerado)
│   ├── stores/
│   │   ├── system.ts                # SystemStore (currentApp, sidebarCollapsed)
│   │   └── lead.ts                  # Store Lead (offline, socket)
│   ├── composables/
│   │   ├── useAppManifest.ts        # Navigation metadata helper
│   │   └── useFastappArchitect.ts   # Schema editor composable
│   ├── utils/
│   │   └── MetaToFlow.ts            # Metadata → Vue Flow (ER/Process)
│   └── types/
│       └── schema.ts                # PropSchema, ObjectSchema, CRUDMode
├── server/
│   ├── api/
│   │   ├── v1/data/[object]/        # 🔌 API Dinâmica
│   │   ├── system/snapshot.post.ts  # 📸 Gera static-manifest.ts
│   │   ├── fastapp-agent.post.ts    # 🤖 LLM Streaming endpoint
│   │   ├── app/                     # CRUD App (admin)
│   │   └── lead/                    # CRUD Lead (nativo)
│   └── utils/
│       ├── prisma.ts                # Singleton PrismaClient
│       ├── dynamic-db.ts            # Hybrid: native ↔ generic Record
│       ├── meta-validation.ts       # Validação meta-driven
│       └── query-parser.ts          # 🔍 Filtros/sort → Prisma where/orderBy
├── prisma/schema.prisma             # Models: App, Lead, Record
└── nuxt.config.ts
```

---

## Camadas Custom sobre o Motor

```mermaid
graph TB
    subgraph "Camada 3 — Custom (Produto)"
        P1["crm/leads.vue (Kanban)"]
        C1["lead/Card, Form, CRUD"]
        S1["stores/lead.ts (offline)"]
    end

    subgraph "Camada 2 — Motor Dinâmico"
        P2["[app]/[module]/[object]/*"]
        D1["core/DynamicCRUD"]
        D2["core/DynamicForm + Fields"]
        D3["core/DynamicTable + List"]
        S2["stores/system.ts"]
    end

    subgraph "Camada 1 — Infraestrutura"
        API_V1["/api/v1/data/:object"]
        API_LEGACY["/api/lead, /api/app"]
        DYNAMIC_DB["dynamic-db.ts"]
        META_VAL["meta-validation.ts"]
        PRISMA["Prisma + PostgreSQL"]
        SNAPSHOT["Snapshot System"]
    end

    P1 --> S1 --> API_LEGACY --> PRISMA
    P2 --> S2 --> SNAPSHOT
    P2 --> D1 --> D2 & D3
    D1 -->|API calls| API_V1
    API_V1 --> META_VAL --> DYNAMIC_DB --> PRISMA

    style P2 fill:#4338ca,color:#fff
    style API_V1 fill:#059669,color:#fff
    style SNAPSHOT fill:#7c3aed,color:#fff
    style P1 fill:#f59e0b,color:#000
```

---

## 🔧 Sovereign Navigation Architecture

A navegação do Fastapp é governada por **dois contextos independentes**:

| Contexto | Controlador | Store | Função |
|---|---|---|---|
| **Navegação** | `AppMenu.vue` (OverlayPanel + rota) | Local (`useFetch`) | Exibir módulos/objetos/páginas do app ativo |
| **Builder** | `BuilderHub.vue` (Dropdown "Contexto") | `systemStore.selectedAppId` | Alvo dos botões Architect/Flow/Agent |

### Builder Hub
Barra superior fixa (`h-14`, `bg-[#0a0d14]`) com:
- **Toggle sidebar** (colapsa `15rem` → `4rem`)
- **Brand** FastApp
- **Dropdown Contexto** (`architect-dropdown`) — define qual app as ferramentas de arquiteto miram
- **Pill Buttons** (segmented controls) — cada ferramenta com sua cor:
  - 🟢 **App** (emerald) → `/{slug}`
  - 🟣 **Architect** (indigo) → `/fastapp/schema-v3?app={id}`
  - 🔵 **Flow** (blue) → `/fastapp/diagram?app={id}`
  - 💜 **Agent** (purple) → `/fastapp/agent?app={id}`

### Sidebar Colapsável
- **Expandida** (`w-60`): ícone + label + headers de módulo
- **Colapsada** (`w-16`): ícones centralizados com tooltip PrimeVue
- Estado persistido em `systemStore.sidebarCollapsed` via `useStorage`

### Ferramentas do Arquiteto

| Ferramenta | Rota | Função |
|---|---|---|
| **FastApp Architect** | `/fastapp/schema-v3` | Schema Studio v3 — editor 3-pane de objetos, propriedades e metadados |
| **FastApp Flow** | `/fastapp/diagram` | Visualização de metadados via Vue Flow (ER e Process modes, Dagre layout) |
| **FastApp Agent** | `/fastapp/agent` | AI Copilot com streaming, contexto vivo e Domain-Aware Gap Analysis |

---

## 🔁 Auto-Evolução (O FastApp como Primeiro App)

O FastApp é **seu próprio usuário mais avançado**. A cadeia de auto-evolução:

```mermaid
graph LR
    AGENT["FastApp Agent<br/>Briefing IA"] -->|"gera schema"| ARCHITECT["FastApp Architect<br/>Schema Studio v3"]
    ARCHITECT -->|"salva draft"| FADAP["FADAP Protocol<br/>Sync Metadata"]
    FADAP -->|"publica snapshot"| MANIFEST["static-manifest.ts"]
    MANIFEST -->|"alimenta"| MENU["AppMenu<br/>Navegação"]
    MANIFEST -->|"alimenta"| FLOW["FastApp Flow<br/>Diagrama"]
    MANIFEST -->|"alimenta"| AGENT
    
    style AGENT fill:#7c3aed,color:#fff
    style ARCHITECT fill:#6366f1,color:#fff
    style FADAP fill:#dc2626,color:#fff
    style FLOW fill:#2563eb,color:#fff
```

> "O motor se usa para se evoluir. Cada melhoria no Schema Manager melhora a capacidade de melhorar o próprio Schema Manager."

---

## Padrões Importantes

### Optimistic Updates
Toda mutação no Lead atualiza o estado local **antes** da resposta do server. Em caso de erro, faz rollback.

### Tab ID (Anti-echo)
Cada aba gera um `tabId` random. Socket.IO ignora eventos da própria aba.

### Dados ↔ App Sincronizados
Toda propriedade nova em `ObjectSchema` deve ser: adicionada ao type, adicionada ao seed, consumida pelo componente.

### Native vs Generic Record
Objetos com model Prisma → desempenho máximo. Objetos do Builder → tabela `Record` genérica, zero setup.

---

## Scripts

```bash
npm run dev          # Nuxt dev + Socket.IO :3001
npm run build        # prisma generate + nuxt build
npx prisma studio    # DB admin GUI
npx prisma db push   # Sync schema → DB
# Seed: /api/seed-system
# Snapshot: botão no /fastapp/apps
```