Public Markdown Document

🏛️ Fastapp Engine — Arquitetura

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

1294 palavras24 headingsrepository root

🏛️ 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: O Norte e as Leis de Abstração.
🏛️ Hierarquia e Metadados: Estrutura de App, Module, Object e Property.
🧬 Taxonomia de Dados: A semântica que governa o comportamento.
🔌 Protocolo Fadap: Sincronização entre Metadados e Storage.
🔄 Sistema de Workflow: Manual técnico de fluxos Human-Led.
🧭 Sistema de Tutoriais: Onboarding interativo com Driver.js.
📱 WAHA Integration: Camada de infraestrutura para WhatsApp (envio + webhook).
📣 Sistema de Comunicados: Painel de regras de notificacao por evento (e-mail + WhatsApp).

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

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

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

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

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

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

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:

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

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

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

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

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:

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

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