{"id":"repo/architecture","source":"repo","sourceLabel":"repository root","sourcePath":"ARCHITECTURE.md","routePath":"/fastapp/public-docs/page/repo/architecture","rawPath":"/fastapp/public-docs/raw/repo/architecture","slug":["repo","architecture"],"slugPath":"repo/architecture","title":"đïž Fastapp Engine â Arquitetura","description":"Documento vivo. Atualizado para refletir o motor Anti Gravity e a Sovereign Navigation Architecture .","headings":["đïž Fastapp Engine â Arquitetura","VisĂŁo Geral","đ DimensĂ”es de Documentação","Stack","Hierarquia: App â Module â Object â Property","Taxonomia SemĂąntica de Objetos","1. Categoria SemĂąntica (object.category)","2. Natureza Arquitetural (object.nature)","3. Relacionamentos (object.relations[])","Matriz Category Ă Nature","Exemplo Concreto: App GestĂŁo de Ativos","Meta API & GestĂŁo de Sistema","1. Snapshot (POST /api/system/snapshot)","2. Schema Evolution (PATCH /api/app/:id)","3. Storage Adaptation (POST /api/data/:object/storage) [Planejado]","4. Admin Portal (Ferramentas de GestĂŁo)","5. Custom Pages & Dynamic Routing","Fluxo de Runtime â Onde vive a inteligĂȘncia","API DinĂąmica v1","Endpoints","EstratĂ©gia HĂbrida: Native vs Generic","Validação Meta Driven","Filtragem & Ordenação (URL Driven)","Sistema de Snapshot"],"wordCount":1294,"markdown":"# đïž Fastapp Engine â Arquitetura\r\n\r\n> Documento vivo. Atualizado para refletir o motor **Anti-Gravity** e a **Sovereign Navigation Architecture**.\r\n\r\n---\r\n\r\n## VisĂŁo Geral\r\n\r\nO **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.\r\n\r\n### đ DimensĂ”es de Documentação\r\n- [đ°ïž **Diretrizes Anti-Gravity**](./ANTIGRAVITY_GUIDELINES.md): O Norte e as Leis de Abstração.\r\n- [đïž **Hierarquia e Metadados**](./APP_HIERARCHY.md): Estrutura de App, Module, Object e Property.\r\n- [𧏠**Taxonomia de Dados**](./DATA_TAXONOMY.md): A semĂąntica que governa o comportamento.\r\n- [đ **Protocolo Fadap**](./FADAP_PROTOCOL.md): Sincronização entre Metadados e Storage.\r\n- [đ **Sistema de Workflow**](./WORKFLOW_SYSTEM.md): Manual tĂ©cnico de fluxos Human-Led.\r\n- [đ§ **Sistema de Tutoriais**](./TUTORIAL_SYSTEM.md): Onboarding interativo com Driver.js.\r\n- [đ± **WAHA Integration**](./WAHA_INTEGRATION.md): Camada de infraestrutura para WhatsApp (envio + webhook).\r\n- [đŁ **Sistema de Comunicados**](./COMUNICADO_SYSTEM.md): Painel de regras de notificacao por evento (e-mail + WhatsApp).\r\n\r\n```mermaid\r\ngraph TB\r\n subgraph \"A FĂĄbrica (Fastapp Engine)\"\r\n SEED[\"đ± Seed / Builder\"]\r\n SNAPSHOT[\"đž Snapshot\"]\r\n API[\"đ API DinĂąmica v1\"]\r\n CORE[\"âïž Core Components\"]\r\n STORE[\"đïž System Store\"]\r\n end\r\n\r\n subgraph \"Modelo 01 (CRM Flux)\"\r\n CRM_PAGES[\"đ Dashboard + Kanban\"]\r\n CRM_COMPS[\"𧩠Lead Components\"]\r\n CRM_STORE[\"đŸ Lead Store + Offline\"]\r\n end\r\n\r\n subgraph \"Modelo 02...N (Futuro)\"\r\n FUTURE[\"đ« Helpdesk, đŠ InventĂĄrio...\"]\r\n end\r\n\r\n SEED --> SNAPSHOT --> STORE\r\n SEED --> API\r\n STORE --> CORE\r\n API --> CORE\r\n CORE --> CRM_PAGES\r\n CORE --> FUTURE\r\n CRM_COMPS --> CRM_PAGES\r\n CRM_STORE --> CRM_PAGES\r\n\r\n style SEED fill:#dc2626,color:#fff\r\n style CORE fill:#4338ca,color:#fff\r\n style API fill:#059669,color:#fff\r\n style SNAPSHOT fill:#7c3aed,color:#fff\r\n```\r\n\r\n---\r\n\r\n## Stack\r\n\r\n| Camada | Tecnologia | VersĂŁo |\r\n|--------|-----------|--------|\r\n| Framework | Nuxt 4 | `^4.3.1` |\r\n| UI Components | PrimeVue (Aura) | `^4.5.4` |\r\n| CSS | Tailwind CSS 3 + CSS custom properties | `^3.4.19` |\r\n| State (Global / UI) | Pinia (`system.ts`) | `^0.11.3` |\r\n| State (Data L3) | Pinia (`appData.ts`) | **SWR + Request Coalescing** |\r\n| Utilities | VueUse (`@vueuse/nuxt`) | `^14.2.1` |\r\n| Forms | VeeValidate + Zod | `^4.15.1` / `^3.25.76` |\r\n| Drag & Drop | vuedraggable | `^4.0.1` |\r\n| Realtime | Socket.IO (client + server) | `^4.8.3` |\r\n| ORM | Prisma | `^6.2.1` |\r\n| DB | PostgreSQL (Supabase) | â |\r\n\r\n---\r\n\r\n## Hierarquia: App â Module â Object â Property\r\n\r\n```mermaid\r\nerDiagram\r\n APP ||--o{ MODULE : \"contains\"\r\n APP ||--o{ OBJECT : \"defines\"\r\n MODULE ||--o{ OBJECT_REF : \"references\"\r\n OBJECT ||--|{ PROPERTY : \"has\"\r\n APP {\r\n string name\r\n string slug\r\n boolean is_active\r\n boolean is_frozen\r\n }\r\n OBJECT {\r\n string name\r\n string label\r\n string type\r\n string crud_mode\r\n string key_property\r\n string label_property\r\n }\r\n PROPERTY {\r\n string name\r\n string label\r\n string type\r\n string content_type\r\n boolean required\r\n boolean show_in_list\r\n boolean show_in_form\r\n }\r\n```\r\n\r\n---\r\n\r\n## Taxonomia SemĂąntica de Objetos\r\n\r\nCada object no Fastapp Ă© classificado por **3 eixos** independentes:\r\n\r\n### 1. Categoria SemĂąntica (`object.category`)\r\n\r\nDefine o \"comportamento de vida\" do dado no ecossistema:\r\n\r\n| Categoria | Descrição | Exemplo | Impacto no Gerador |\r\n|-----------|-----------|---------|-------------------|\r\n| `master` | Dado mestre, estĂĄvel, base para outros | Broker, AssetClass, User | Caches, dropdowns globais, busca por nome |\r\n| `transactional` | Eventos, registros de fluxo, alta volatilidade | Transaction, Lead, UserAsset | Ăndices por data, logs de auditoria, filtros de perĂodo |\r\n| `configuration` | ParĂąmetros do sistema ou do usuĂĄrio | AppSettings, WalletProfile | Interfaces simplificadas (\"Settings Page\") |\r\n\r\n### 2. Natureza Arquitetural (`object.nature`)\r\n\r\nDefine **onde** o dado mora fisicamente:\r\n\r\n| Natureza | Armazenamento | Comportamento |\r\n|----------|--------------|---------------|\r\n| `physical` | Tabela prĂłpria no DB | ID Ășnico global, referenciĂĄvel por qualquer um |\r\n| `embedded` | Dentro do JSON do pai | Sem tabela prĂłpria; morre se o pai for deletado |\r\n| `virtual` | Calculado em runtime | AgregaçÔes (ex: total_balance do usuĂĄrio) |\r\n\r\n### 3. Relacionamentos (`object.relations[]`)\r\n\r\n**Tipos de VĂnculo:**\r\n\r\n| `relation.type` | SemĂąntica | Exemplo |\r\n|-----------------|-----------|---------|\r\n| `belongs_to` | ReferĂȘncia a um master ou pai | UserAsset â Broker |\r\n| `has_one` | Propriedade de um filho Ășnico | User â WalletProfile |\r\n| `has_many` | Propriedade de uma coleção | WalletProfile â UserAsset[] |\r\n| `associates_with` | Relação N:N | Tag â Lead |\r\n\r\n**EstratĂ©gias de PersistĂȘncia:**\r\n\r\n| `relation.storage` | Como se salva | Quando usar |\r\n|---------------------|---------------|-------------|\r\n| `reference_id` | Salva apenas o ID (FK relacional) | Dados independentes |\r\n| `document_embed` | Salva o objeto inteiro no JSON | Dados acoplados ao pai |\r\n| `pivot` | Tabela intermediĂĄria | Relação N:N |\r\n\r\n### Matriz Category Ă Nature\r\n\r\n```mermaid\r\ngraph TD\r\n subgraph \"master\"\r\n M_P[\"physical
Broker, AssetClass
Tabela prĂłpria\"]\r\n M_E[\"embedded
â
(raro)\"]\r\n M_V[\"virtual
â
(raro)\"]\r\n end\r\n\r\n subgraph \"transactional\"\r\n T_P[\"physical
Lead, UserAsset
Tabela c/ Ăndices\"]\r\n T_E[\"embedded
Transaction
JSON no pai\"]\r\n T_V[\"virtual
TotalBalance
Calculado\"]\r\n end\r\n\r\n subgraph \"configuration\"\r\n C_P[\"physical
WalletProfile
Tabela simples\"]\r\n C_E[\"embedded
AppSettings
JSON no App\"]\r\n C_V[\"virtual
â
(raro)\"]\r\n end\r\n\r\n style M_P fill:#059669,color:#fff\r\n style T_P fill:#2563eb,color:#fff\r\n style T_E fill:#7c3aed,color:#fff\r\n style T_V fill:#d97706,color:#fff\r\n style C_P fill:#64748b,color:#fff\r\n```\r\n\r\n### Exemplo Concreto: App GestĂŁo de Ativos\r\n\r\n```mermaid\r\nerDiagram\r\n BROKER ||--o{ USER_ASSET : \"belongs_to (reference_id)\"\r\n ASSET_CLASS ||--o{ USER_ASSET : \"belongs_to (reference_id)\"\r\n USER_ASSET ||--|{ TRANSACTION : \"has_many (document_embed)\"\r\n WALLET_PROFILE ||--o{ USER_ASSET : \"has_many (reference_id)\"\r\n\r\n BROKER {\r\n string name\r\n string cnpj\r\n category master\r\n nature physical\r\n }\r\n ASSET_CLASS {\r\n string name\r\n enum risk_level\r\n category master\r\n nature physical\r\n }\r\n USER_ASSET {\r\n string ticker\r\n number quantity\r\n number avg_price\r\n category transactional\r\n nature physical\r\n }\r\n TRANSACTION {\r\n date date\r\n enum type\r\n number quantity\r\n number price\r\n category transactional\r\n nature embedded\r\n }\r\n WALLET_PROFILE {\r\n string name\r\n number target_conservative\r\n category configuration\r\n nature physical\r\n }\r\n```\r\n\r\n\r\n---\r\n\r\n## Meta-API & GestĂŁo de Sistema\r\n\r\nAlĂ©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.\r\n\r\n### 1. Snapshot (`POST /api/system/snapshot`)\r\n- **Função**: Gera uma \"foto\" estĂĄtica do estado atual do banco (Apps, Objetos, Campos) em `app/fastapp/static-manifest.ts`.\r\n- **Uso**: Freeze de versĂŁo para produção ou backup de schema.\r\n\r\n### 2. Schema Evolution (`PATCH /api/app/:id`)\r\n- **Função**: Permite alterar definiçÔes de objetos (adicionar campos, mudar layout) via API.\r\n- **Uso**: Editores visuais (Builder) ou scripts de migração (ex: `apply-layout-grid.ts`).\r\n\r\n### 3. Storage Adaptation (`POST /api/data/:object/storage`) [Planejado]\r\n- **Função**: Analisa a definição do objeto e executa DDL (Create/Alter Table) para alinhar o banco fĂsico.\r\n- **Uso**: Transformar um objeto \"Generic\" (JSON) em \"Native\" (Tabela SQL) para performance, sem reiniciar o servidor.\r\n\r\n### 4. Admin Portal (Ferramentas de GestĂŁo)\r\n- **Schema Manager**: Interface visual para editar Apps e Objetos (`PATCH /api/app`). Alavanca componentes dinĂąmicos para editar a si mesmo.\r\n- **API Tester**: \"Mini Postman\" integrado para testar endpoints do sistema (`/api/v1/data`) e validar respostas.\r\n- **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.\r\n\r\n### 5. Custom Pages & Dynamic Routing\r\n- **Configuração**: O manifesto suporta uma lista de `pages`.\r\n- **Roteamento**: \r\n - `page.type === 'custom'`: Aponta para um arquivo fĂsico em `pages/`.\r\n - `page.type === 'dynamic_crud'`: Gera automaticamente a rota para o objeto.\r\n- **Visibilidade**: O `AppMenu.vue` resolve essas rotas dinamicamente para o sidebar.\r\n\r\n---\r\n\r\n## Fluxo de Runtime â Onde vive a inteligĂȘncia\r\n\r\n```mermaid\r\nsequenceDiagram\r\n participant URL as Browser URL\r\n participant Page as Dynamic Page\r\n participant Store as System Store\r\n participant Static as static-manifest.ts\r\n participant API as /api/app (GET)\r\n participant DataAPI as /api/v1/data/:object\r\n participant DynDB as dynamic-db.ts\r\n participant NativeModel as Prisma Model (Lead)\r\n participant RecordTable as Record Table (Generic)\r\n\r\n URL->>Page: /crm/crm/lead\r\n Page->>Store: fetchDefs()\r\n Page->>AppData: fetchObjectData('lead') - non-blocking SWR\r\n \r\n Note over AppData: Checking for pending promises...\r\n alt Already fetching (Request Coalescing)\r\n AppData-->>Page: await the same existing promise â\r\n else Not in cache\r\n AppData->>DataAPI: GET /api/v1/data/lead?$limit=100\r\n DataAPI-->>AppData: Data[]\r\n AppData-->>Page: Hydrated data â\r\n end\r\n\r\n alt is_static (Snapshot ativo)\r\n Store->>Static: import StaticManifest\r\n Static-->>Store: App[] (instantĂąneo)\r\n else is_live (Dev / sem snapshot)\r\n Store->>API: GET /api/app\r\n API-->>Store: App[] (do banco)\r\n end\r\n\r\n Store-->>Page: objectSchema resolved\r\n Page->>DataAPI: GET /api/v1/data/lead\r\n\r\n DataAPI->>DynDB: isNativeModel(\"lead\")?\r\n\r\n alt Modelo nativo existe\r\n DynDB->>NativeModel: prisma.lead.findMany()\r\n NativeModel-->>DataAPI: Lead[]\r\n else Modelo genĂ©rico (ex: tarefa)\r\n DynDB->>RecordTable: prisma.record.findMany(object_name)\r\n RecordTable-->>DataAPI: Record[] â flatten JSON\r\n end\r\n\r\n DataAPI-->>Page: data[]\r\n```\r\n\r\n---\r\n\r\n## API DinĂąmica v1\r\n\r\n### Endpoints\r\n\r\n| Rota | MĂ©todo | Descrição |\r\n|------|--------|-----------|\r\n| `/api/v1/data/:object` | GET | Lista (com filtros e ordenação via query params) |\r\n| `/api/v1/data/:object` | POST | Cria (com validação meta-driven) |\r\n| `/api/v1/data/:object/:id` | GET | Busca por ID |\r\n| `/api/v1/data/:object/:id` | PATCH | Atualiza (com validação) |\r\n| `/api/v1/data/:object/:id` | DELETE | Remove |\r\n\r\n### EstratĂ©gia HĂbrida: Native vs Generic\r\n\r\n```mermaid\r\ngraph LR\r\n REQ[\"Request /api/v1/data/:object\"]\r\n META[\"meta-validation.ts
Resolve properties do manifest\"]\r\n DYN[\"dynamic-db.ts
isNativeModel?\"]\r\n\r\n subgraph \"Caminho A: Native\"\r\n PRISMA[\"prisma.lead / prisma.app
Model dedicado\"]\r\n end\r\n\r\n subgraph \"Caminho B: Generic\"\r\n RECORD[\"prisma.record
data: Json + object_name\"]\r\n FLATTEN[\"Flatten: {id, ...data, timestamps}\"]\r\n end\r\n\r\n REQ --> META --> DYN\r\n DYN -->|\"lead, app\"| PRISMA\r\n DYN -->|\"tarefa, contato, ...\"| RECORD --> FLATTEN\r\n\r\n style PRISMA fill:#059669,color:#fff\r\n style RECORD fill:#7c3aed,color:#fff\r\n```\r\n\r\n- **Native**: objetos com model Prisma dedicado (`lead`, `app`). Performance mĂĄxima.\r\n- **Generic**: objetos criados no Builder. Usam tabela `Record` com `data Json`. Zero setup.\r\n\r\n### Validação Meta-Driven\r\n\r\n```mermaid\r\ngraph TD\r\n BODY[\"Request Body\"] --> RESOLVE[\"resolveObjectProperties(name)\"]\r\n RESOLVE --> VALIDATE[\"validateBody(body, properties)\"]\r\n VALIDATE -->|\"required fields\"| CHECK_REQ[\"Campos obrigatĂłrios presentes?\"]\r\n VALIDATE -->|\"type checking\"| CHECK_TYPE[\"string/number/boolean correto?\"]\r\n CHECK_REQ -->|\"â\"| ERR400[\"400: Validation failed\"]\r\n CHECK_TYPE -->|\"â\"| ERR400\r\n VALIDATE -->|\"â\"| CLEAN[\"cleanBody(body, properties)\"]\r\n CLEAN -->|\"strip _tabId, unknowns\"| SAVE[\"Save to DB\"]\r\n\r\n style ERR400 fill:#dc2626,color:#fff\r\n style SAVE fill:#059669,color:#fff\r\n```\r\n\r\n### Filtragem & Ordenação (URL-Driven)\r\n\r\nA API aceita filtros e ordenação via query params. O frontend usa a URL como **fonte Ășnica de verdade**.\r\n\r\n**Query Parser** (`server/utils/query-parser.ts`):\r\n\r\nO motor agora prioriza o formato **Flattened** para query strings, facilitando a integração com APIs externas.\r\n\r\n| Operador | Formato Flat (Soberano) | Formato Legado (Legacy) | Descrição |\r\n|----------|----------------|----------------|-----------|\r\n| `=` | `?campo=valor` | `?filters[campo][=]=valor` | Igualdade simples |\r\n| `ne` | `?campo[ne]=valor` | `?filters[campo][$ne]=valor` | Diferente |\r\n| `gt` / `gte` | `?campo[gt]=5` | `?filters[campo][$gt]=5` | Maior que / Maior ou igual |\r\n| `lt` / `lte` | `?campo[lt]=10` | `?filters[campo][$lte]=10` | Menor que / Menor ou igual |\r\n| `like` | `?campo[like]=mario`| `?filters[campo][$like]=mario` | Busca textual (Case Insensitive) |\r\n| `between`| `?campo[between]=a,b`| `?filters[campo][between]=a,b` | Intervalo de valores |\r\n\r\n**Paginação e Ordenação Soberana:**\r\n\r\n| ParĂąmetro | Tipo | Descrição | Exemplo |\r\n|-----------|------|-----------|---------|\r\n| `$limit` | `number` | Quantidade de registros por pĂĄgina | `?$limit=50` |\r\n| `$skip` | `number` | Quantidade de registros a pular | `?$skip=100` |\r\n| `$sort[f]`| `1 / -1`| Ordenação (1=ASC, -1=DESC) | `?$sort[name]=1` |\r\n| `granularity`| `string`| Resolução temporal para BI | `?granularity=week` |\r\n\r\n**Coerção automĂĄtica**: `\"true\"` â `boolean`, `\"42\"` â `number`, `\"null\"` â `null`.\r\n\r\n**Fluxo URL-Driven:**\r\n\r\n```mermaid\r\nsequenceDiagram\r\n participant User as UsuĂĄrio\r\n participant Filter as CoreDynamicFilter\r\n participant URL as URL (query params)\r\n participant Page as index.vue\r\n participant API as /api/v1/data/:object\r\n participant Table as CoreDynamicTable\r\n\r\n Note over Filter: onMounted â readFromUrl()\r\n User->>Filter: Seleciona campo, operador, valor\r\n Filter->>URL: router.replace({ query })\r\n URL->>Page: watch(route.query) dispara\r\n Page->>API: GET /api/v1/data/lead?filters[status][=]=NOVO\r\n API-->>Page: data[] filtrado\r\n Page->>Table: :data=\"data\"\r\n Note over URL: URL bookmarkĂĄvel e compartilhĂĄvel\r\n```\r\n\r\n- **Native models**: filtros viram clĂĄusula `where` do Prisma (performĂĄtico)\r\n- **Generic records**: filtros aplicados in-memory apĂłs fetch (JSON field)\r\n\r\n---\r\n\r\n## Sistema de Snapshot\r\n\r\n```mermaid\r\nsequenceDiagram\r\n participant Admin as Admin Panel\r\n participant API as POST /api/system/snapshot\r\n participant DB as PostgreSQL\r\n participant FS as Filesystem\r\n participant Store as System Store\r\n\r\n Admin->>API: Clique \"Gerar Snapshot\"\r\n API->>DB: prisma.app.findMany()\r\n DB-->>API: App[] (com modules/objects JSON)\r\n API->>FS: writeFileSync(static-manifest.ts)\r\n FS-->>API: Arquivo gerado\r\n API-->>Admin: Toast \"Snapshot gerado!\"\r\n\r\n Note over Store: No prĂłximo boot (produção):\r\n Store->>FS: import StaticManifest\r\n Note over Store: is_static = true, sem DB\r\n```\r\n\r\n### Smart Store â Prioridade de Dados\r\n\r\n| Condição | Fonte | `is_static` |\r\n|----------|-------|-----------|\r\n| `StaticManifest.length > 0` + produção | Arquivo estĂĄtico | `true` |\r\n| Dev mode (`import.meta.dev`) | API `/api/app` | `false` |\r\n| API falha + manifest existe | Arquivo estĂĄtico (fallback) | `true` |\r\n| Nenhum manifest + API ok | API `/api/app` | `false` |\r\n\r\n### `is_frozen` no App\r\n\r\nCada App pode ter `is_frozen: true`. Quando congelado, o sistema ignora a API e usa exclusivamente o arquivo estĂĄtico â simulando produção \"compilada\".\r\n\r\n---\r\n\r\n## Componentes Core\r\n\r\n```mermaid\r\ngraph TD\r\n subgraph \"Navegação Soberana\"\r\n HUB[\"CoreBuilderHub
Top bar contextual\"]\r\n MENU[\"CoreAppMenu
Sidebar colapsåvel\"]\r\n end\r\n\r\n subgraph \"Orquestração\"\r\n CRUD[\"CoreDynamicCRUD
mode: modal|page|inline\"]\r\n end\r\n\r\n subgraph \"Visualização\"\r\n TABLE[\"CoreDynamicTable
columns via show_in_list\"]\r\n LIST[\"CoreDynamicList
edição in-place\"]\r\n end\r\n\r\n subgraph \"Filtros\"\r\n FILTER[\"CoreDynamicFilter
URL-driven, adaptive inputs\"]\r\n end\r\n\r\n subgraph \"FormulĂĄrio\"\r\n FORM[\"CoreDynamicForm
VeeValidate + Zod runtime\"]\r\n FIELDS[\"CoreDynamicFields
recursivo, layout vertical|inline\"]\r\n RENDERER[\"CoreFieldRenderer
type â PrimeVue\"]\r\n end\r\n\r\n subgraph \"Ferramentas do Arquiteto\"\r\n ARCHITECT[\"FastApp Architect
Schema Studio v3\"]\r\n FLOW[\"FastApp Flow
Visual Metadata Explorer\"]\r\n AGENT[\"FastApp Agent
Enterprise AI Copilot\"]\r\n end\r\n\r\n HUB -->|contexto builder| ARCHITECT & FLOW & AGENT\r\n MENU -->|contexto navegação| CRUD\r\n CRUD --> TABLE & LIST\r\n CRUD -->|Dialog| FORM\r\n FORM --> FIELDS\r\n FIELDS -->|inner_collection| FIELDS\r\n FIELDS --> RENDERER\r\n\r\n style CRUD fill:#4338ca,color:#fff\r\n style FORM fill:#059669,color:#fff\r\n style HUB fill:#0a0d14,color:#e2e8f0,stroke:#4338ca\r\n style ARCHITECT fill:#6366f1,color:#fff\r\n style FLOW fill:#2563eb,color:#fff\r\n style AGENT fill:#7c3aed,color:#fff\r\n```\r\n\r\n### Props & Eventos\r\n\r\n| Componente | Props | Eventos |\r\n|-----------|-------|---------|\r\n| `CoreDynamicCRUD` | `schema`, `data`, `mode`, `objectName` | `create`, `update`, `delete`, `edit-click` |\r\n| `CoreDynamicTable` | `schema`, `data` | `edit`, `delete` |\r\n| `CoreDynamicList` | `schema`, `data`, `editable` | `edit`, `delete`, `update` |\r\n| `CoreDynamicForm` | `properties`, `initialValues` | `submit` |\r\n| `CoreDynamicFields` | `properties`, `values`, `errors`, `prefix`, `setFieldValue`, `layout` | â |\r\n| `CoreFieldRenderer` | `property`, `modelValue` | `update:modelValue` |\r\n\r\n### CRUD Modes\r\n\r\n| Modo | Criar | Editar | View Default |\r\n|------|-------|--------|-------------|\r\n| `modal` | Dialog | Dialog | Table |\r\n| `page` | `/create` | `/[id]` | Table |\r\n| `inline` | Dialog | In-place na lista | List |\r\n\r\n---\r\n\r\n## Banco de Dados\r\n\r\n```prisma\r\nmodel App {\r\n id Int @id @default(autoincrement())\r\n name String\r\n slug String @unique\r\n description String?\r\n version String @default(\"1.0.0\")\r\n icon String @default(\"pi pi-box\")\r\n is_active Boolean @default(true)\r\n is_frozen Boolean @default(false)\r\n created_at DateTime @default(now())\r\n modules Json @default(\"[]\")\r\n objects Json @default(\"[]\")\r\n}\r\n\r\nmodel Lead {\r\n id Int @id @default(autoincrement())\r\n nome String\r\n email String\r\n whatsapp String\r\n status String @default(\"NOVO\")\r\n ordem Int @default(0)\r\n}\r\n\r\nmodel Record {\r\n id Int @id @default(autoincrement())\r\n object_name String\r\n data Json @default(\"{}\")\r\n created_at DateTime @default(now())\r\n updated_at DateTime @updatedAt\r\n @@index([object_name])\r\n}\r\n```\r\n\r\n**Lead** = model nativo (performance). **Record** = tabela genĂ©rica para objetos dinĂąmicos.\r\n\r\n---\r\n\r\n## Estrutura de DiretĂłrios\r\n\r\n```\r\nlead-nuxt/\r\nâââ app/\r\nâ âââ components/\r\nâ â âââ core/ # âïž Motor dinĂąmico\r\nâ â â âââ BuilderHub.vue # đ§ Top bar contextual (Sovereign Nav)\r\nâ â â âââ AppMenu.vue # đ Sidebar colapsĂĄvel (route-driven)\r\nâ â â âââ DynamicCRUD.vue # Orquestrador (modal/page/inline)\r\nâ â â âââ DynamicFilter.vue # đ Filtro universal (URL-driven)\r\nâ â â âââ DynamicTable.vue # DataTable por metadados\r\nâ â â âââ DynamicList.vue # List view com inline editing\r\nâ â â âââ DynamicForm.vue # Zod runtime + VeeValidate (recursivo)\r\nâ â â âââ DynamicFields.vue # Recursivo (inner_collection, Ontology v3)\r\nâ â â âââ FieldRenderer.vue # type â PrimeVue component\r\nâ â â âââ AssetUpload.vue # Upload para semantic: asset\r\nâ â â âââ MapRenderer.vue # Mapa L2 (spatial_type: point)\r\nâ â âââ fastapp/ # đïž Ferramentas do Arquiteto\r\nâ â â âââ AgentChat.vue # Chat streaming com AI Architect\r\nâ â â âââ FastNode.vue # Node customizado para Vue Flow\r\nâ â â âââ PropertyListEditor # Editor visual de propriedades\r\nâ â â âââ SchemaPropertyMgr # Manager de schemas v3\r\nâ â âââ crm/ # đ Custom: CRM Flux\r\nâ â âââ sosplantao/ # đ„ Custom: SosPlantĂŁo\r\nâ â âââ central-filtros/ # đ Custom: Central Filtros\r\nâ â âââ lead/ # đ€ Custom: Lead (ArquĂ©tipo)\r\nâ âââ layouts/\r\nâ â âââ default.vue # Shell: BuilderHub + Sidebar + Content\r\nâ âââ pages/\r\nâ â âââ fastapp/\r\nâ â â âââ apps.vue # Gerenciador + Snapshot\r\nâ â â âââ schema-v3.vue # đïž FastApp Architect (3-pane)\r\nâ â â âââ diagram.vue # đșïž FastApp Flow (Vue Flow)\r\nâ â â âââ agent.vue # đ€ FastApp Agent (AI Copilot)\r\nâ â âââ [app]/\r\nâ â â âââ index.vue # App Dashboard\r\nâ â â âââ [module]/index.vue # Module Dashboard (Focal)\r\nâ â â âââ [module]/[object]/ # đ Rotas dinĂąmicas\r\nâ â âââ crm/ # Custom pages\r\nâ âââ fastapp/\r\nâ â âââ manifest.ts # Types: App, Module, Object, Property\r\nâ â âââ static-manifest.ts # đž Snapshot (auto-gerado)\r\nâ âââ stores/\r\nâ â âââ system.ts # SystemStore (currentApp, sidebarCollapsed)\r\nâ â âââ lead.ts # Store Lead (offline, socket)\r\nâ âââ composables/\r\nâ â âââ useAppManifest.ts # Navigation metadata helper\r\nâ â âââ useFastappArchitect.ts # Schema editor composable\r\nâ âââ utils/\r\nâ â âââ MetaToFlow.ts # Metadata â Vue Flow (ER/Process)\r\nâ âââ types/\r\nâ âââ schema.ts # PropSchema, ObjectSchema, CRUDMode\r\nâââ server/\r\nâ âââ api/\r\nâ â âââ v1/data/[object]/ # đ API DinĂąmica\r\nâ â âââ system/snapshot.post.ts # đž Gera static-manifest.ts\r\nâ â âââ fastapp-agent.post.ts # đ€ LLM Streaming endpoint\r\nâ â âââ app/ # CRUD App (admin)\r\nâ â âââ lead/ # CRUD Lead (nativo)\r\nâ âââ utils/\r\nâ âââ prisma.ts # Singleton PrismaClient\r\nâ âââ dynamic-db.ts # Hybrid: native â generic Record\r\nâ âââ meta-validation.ts # Validação meta-driven\r\nâ âââ query-parser.ts # đ Filtros/sort â Prisma where/orderBy\r\nâââ prisma/schema.prisma # Models: App, Lead, Record\r\nâââ nuxt.config.ts\r\n```\r\n\r\n---\r\n\r\n## Camadas Custom sobre o Motor\r\n\r\n```mermaid\r\ngraph TB\r\n subgraph \"Camada 3 â Custom (Produto)\"\r\n P1[\"crm/leads.vue (Kanban)\"]\r\n C1[\"lead/Card, Form, CRUD\"]\r\n S1[\"stores/lead.ts (offline)\"]\r\n end\r\n\r\n subgraph \"Camada 2 â Motor DinĂąmico\"\r\n P2[\"[app]/[module]/[object]/*\"]\r\n D1[\"core/DynamicCRUD\"]\r\n D2[\"core/DynamicForm + Fields\"]\r\n D3[\"core/DynamicTable + List\"]\r\n S2[\"stores/system.ts\"]\r\n end\r\n\r\n subgraph \"Camada 1 â Infraestrutura\"\r\n API_V1[\"/api/v1/data/:object\"]\r\n API_LEGACY[\"/api/lead, /api/app\"]\r\n DYNAMIC_DB[\"dynamic-db.ts\"]\r\n META_VAL[\"meta-validation.ts\"]\r\n PRISMA[\"Prisma + PostgreSQL\"]\r\n SNAPSHOT[\"Snapshot System\"]\r\n end\r\n\r\n P1 --> S1 --> API_LEGACY --> PRISMA\r\n P2 --> S2 --> SNAPSHOT\r\n P2 --> D1 --> D2 & D3\r\n D1 -->|API calls| API_V1\r\n API_V1 --> META_VAL --> DYNAMIC_DB --> PRISMA\r\n\r\n style P2 fill:#4338ca,color:#fff\r\n style API_V1 fill:#059669,color:#fff\r\n style SNAPSHOT fill:#7c3aed,color:#fff\r\n style P1 fill:#f59e0b,color:#000\r\n```\r\n\r\n---\r\n\r\n## đ§ Sovereign Navigation Architecture\r\n\r\nA navegação do Fastapp Ă© governada por **dois contextos independentes**:\r\n\r\n| Contexto | Controlador | Store | Função |\r\n|---|---|---|---|\r\n| **Navegação** | `AppMenu.vue` (OverlayPanel + rota) | Local (`useFetch`) | Exibir mĂłdulos/objetos/pĂĄginas do app ativo |\r\n| **Builder** | `BuilderHub.vue` (Dropdown \"Contexto\") | `systemStore.selectedAppId` | Alvo dos botĂ”es Architect/Flow/Agent |\r\n\r\n### Builder Hub\r\nBarra superior fixa (`h-14`, `bg-[#0a0d14]`) com:\r\n- **Toggle sidebar** (colapsa `15rem` â `4rem`)\r\n- **Brand** FastApp\r\n- **Dropdown Contexto** (`architect-dropdown`) â define qual app as ferramentas de arquiteto miram\r\n- **Pill Buttons** (segmented controls) â cada ferramenta com sua cor:\r\n - đą **App** (emerald) â `/{slug}`\r\n - đŁ **Architect** (indigo) â `/fastapp/schema-v3?app={id}`\r\n - đ” **Flow** (blue) â `/fastapp/diagram?app={id}`\r\n - đ **Agent** (purple) â `/fastapp/agent?app={id}`\r\n\r\n### Sidebar ColapsĂĄvel\r\n- **Expandida** (`w-60`): Ăcone + label + headers de mĂłdulo\r\n- **Colapsada** (`w-16`): Ăcones centralizados com tooltip PrimeVue\r\n- Estado persistido em `systemStore.sidebarCollapsed` via `useStorage`\r\n\r\n### Ferramentas do Arquiteto\r\n\r\n| Ferramenta | Rota | Função |\r\n|---|---|---|\r\n| **FastApp Architect** | `/fastapp/schema-v3` | Schema Studio v3 â editor 3-pane de objetos, propriedades e metadados |\r\n| **FastApp Flow** | `/fastapp/diagram` | Visualização de metadados via Vue Flow (ER e Process modes, Dagre layout) |\r\n| **FastApp Agent** | `/fastapp/agent` | AI Copilot com streaming, contexto vivo e Domain-Aware Gap Analysis |\r\n\r\n---\r\n\r\n## đ Auto-Evolução (O FastApp como Primeiro App)\r\n\r\nO FastApp Ă© **seu prĂłprio usuĂĄrio mais avançado**. A cadeia de auto-evolução:\r\n\r\n```mermaid\r\ngraph LR\r\n AGENT[\"FastApp Agent
Briefing IA\"] -->|\"gera schema\"| ARCHITECT[\"FastApp Architect
Schema Studio v3\"]\r\n ARCHITECT -->|\"salva draft\"| FADAP[\"FADAP Protocol
Sync Metadata\"]\r\n FADAP -->|\"publica snapshot\"| MANIFEST[\"static-manifest.ts\"]\r\n MANIFEST -->|\"alimenta\"| MENU[\"AppMenu
Navegação\"]\r\n MANIFEST -->|\"alimenta\"| FLOW[\"FastApp Flow
Diagrama\"]\r\n MANIFEST -->|\"alimenta\"| AGENT\r\n \r\n style AGENT fill:#7c3aed,color:#fff\r\n style ARCHITECT fill:#6366f1,color:#fff\r\n style FADAP fill:#dc2626,color:#fff\r\n style FLOW fill:#2563eb,color:#fff\r\n```\r\n\r\n> \"O motor se usa para se evoluir. Cada melhoria no Schema Manager melhora a capacidade de melhorar o prĂłprio Schema Manager.\"\r\n\r\n---\r\n\r\n## PadrĂ”es Importantes\r\n\r\n### Optimistic Updates\r\nToda mutação no Lead atualiza o estado local **antes** da resposta do server. Em caso de erro, faz rollback.\r\n\r\n### Tab ID (Anti-echo)\r\nCada aba gera um `tabId` random. Socket.IO ignora eventos da prĂłpria aba.\r\n\r\n### Dados â App Sincronizados\r\nToda propriedade nova em `ObjectSchema` deve ser: adicionada ao type, adicionada ao seed, consumida pelo componente.\r\n\r\n### Native vs Generic Record\r\nObjetos com model Prisma â desempenho mĂĄximo. Objetos do Builder â tabela `Record` genĂ©rica, zero setup.\r\n\r\n---\r\n\r\n## Scripts\r\n\r\n```bash\r\nnpm run dev # Nuxt dev + Socket.IO :3001\r\nnpm run build # prisma generate + nuxt build\r\nnpx prisma studio # DB admin GUI\r\nnpx prisma db push # Sync schema â DB\r\n# Seed: /api/seed-system\r\n# Snapshot: botĂŁo no /fastapp/apps\r\n```\r\n"}