> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unicontrol.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Arquitetura

> Visao geral da arquitetura do monorepo Portal — plataforma de gestao smart home/IoT

# Arquitetura do Portal

Visao geral da arquitetura do monorepo Portal — plataforma de gestao smart home/IoT.

## Visao Geral (alto nível)

```mermaid theme={null}
flowchart LR
    %% Clients
    subgraph Clients["Clientes"]
        Dashboard["Dashboard<br/>(React + Vite)"]
        Mobile["Mobile<br/>(Flutter)"]
        CLI["CLI<br/>(Cliffy)"]
    end

    %% Core
    subgraph Core["packages/core (API)"]
        direction TB
        Web["Hono HTTP Routes<br/>/v1/*"]
        UseCases["Use Cases"]
        Domain["Domain Entities<br/>+ Repositories"]
        EventBus["Event Bus<br/>(shared/event-emitter)"]
        ServiceReg["Service Registry<br/>integration.domain.service"]
    end

    %% Edges / Workers
    subgraph Edges["Edges (SDK runtime)"]
        WorkerHome["Worker HOME<br/>(Raspberry/servidor local)"]
        WorkerCloud["Worker CLOUD<br/>(cluster Portal)"]
        WorkerAuto["worker-automation<br/>(automacoes)"]
    end

    %% SDK
    SDK["packages/sdk<br/>integracoes + edge runtime"]

    %% Infra
    subgraph Infra["Infraestrutura"]
        Postgres[("PostgreSQL<br/>Drizzle ORM")]
        Redis[("Redis")]
        EMQX{{"EMQX MQTT<br/>broker"}}
        Consul[("Consul")]
        Vault[("Vault")]
        Influx[("InfluxDB")]
    end

    %% Third party
    subgraph ThirdParty["Servicos externos"]
        Logto["Logto<br/>(OAuth)"]
        Stripe["Stripe<br/>(billing)"]
        Alexa["Alexa Smart Home"]
        AppleIAP["Apple IAP"]
        Cloudflare["Cloudflare"]
        Directus["Directus CMS"]
        Odoo["Odoo Helpdesk"]
        Calendly["Calendly"]
        Pangolin["Pangolin"]
    end

    %% Connections
    Dashboard -- "HTTP REST" --> Web
    Mobile -- "HTTP REST" --> Web
    CLI -- "HTTP REST" --> Web

    Web --> UseCases
    UseCases --> Domain
    UseCases --> EventBus
    UseCases --> ServiceReg
    Domain --> Postgres

    Web -. "auth JWT" .-> Logto
    UseCases -. "config/secrets" .-> Consul
    UseCases -. "config/secrets" .-> Vault
    UseCases -- "pagamentos" --> Stripe
    UseCases -- "IAP" --> AppleIAP
    UseCases -- "Smart Home v3" --> Alexa
    UseCases -- "CDN/DNS" --> Cloudflare
    UseCases -- "tickets" --> Odoo
    UseCases -- "agenda" --> Calendly
    UseCases -- "tunneling" --> Pangolin
    UseCases -- "CMS" --> Directus
    UseCases -- "cache" --> Redis
    UseCases -- "metricas" --> Influx

    ServiceReg <-- "MQTT pub/sub" --> EMQX
    EMQX <-- "MQTT pub/sub" --> WorkerHome
    EMQX <-- "MQTT pub/sub" --> WorkerCloud
    EMQX <-- "MQTT pub/sub" --> WorkerAuto

    WorkerHome --> SDK
    WorkerCloud --> SDK
    WorkerAuto --> Postgres
    UseCases -. "registry de integracoes" .-> SDK
```

## Packages do monorepo

| Package                      | Papel                                                                                                                                                                                                              |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `packages/core`              | API REST (Hono + Deno). Clean Architecture com domain / application / infrastructure. Concentra autenticação, billing, config-flows, automações, integrações Alexa, registro de devices/entities.                  |
| `packages/dashboard`         | Frontend web (React + Vite + Zustand + Tailwind). Consome a API do core via HTTP.                                                                                                                                  |
| `packages/mobile`            | App Flutter (iOS/Android). Consome a API via HTTP e recebe push notifications.                                                                                                                                     |
| `packages/sdk`               | Biblioteca compartilhada de integrações (Tuya, KNX, Zigbee, LG ThinQ, Spotify, Discord, Broadlink, Roku, Shelly, TTLock, etc.) + runtime de edge (`edge-bootstrap-client`, `shared-mqtt-client`, `offline-queue`). |
| `packages/worker`            | Runtime de edge (HOME ou CLOUD) que carrega o SDK e executa I/O de devices, publicando estados via MQTT.                                                                                                           |
| `packages/worker-automation` | Engine de execução de automações; consome eventos MQTT e le/grava no Postgres compartilhado.                                                                                                                       |
| `packages/cli`               | Ferramenta de linha de comando (Cliffy) para operações administrativas.                                                                                                                                            |

## Arquitetura interna do `core`

```mermaid theme={null}
flowchart TB
    subgraph CoreSrc["packages/core/src"]
        direction TB

        subgraph DomainLayer["domain (regra de negocio pura)"]
            Entities["entity/<br/>User, ConfigEntry, Automation, State, ..."]
            Repos["repository/<br/>interfaces (IUserRepository, ...)"]
            Components["components/<br/>light, switch, climate, ..."]
        end

        subgraph AppLayer["application (orquestracao)"]
            UC["use-cases/<br/>add-knx-device, create-automation, ..."]
            Services["services/<br/>service-registry, notification, oauth"]
            CFH["config-flow-handlers/"]
            IH["integration-handlers/"]
        end

        Shared["shared/<br/>event-emitter (bus tipado)"]

        subgraph InfraLayer["infrastructure"]
            direction TB
            Persistence["adapters/persistence/<br/>Postgres + Directus repos"]
            External["adapters/external/<br/>mqtt, redis, stripe, logto, vault, consul,<br/>influxdb, cloudflare, apple-iap, calendly,<br/>odoo, pangolin, directus, amazon"]
            CompAdapters["adapters/components/<br/>tuya/, knx/, lg_thinq/, alexa/, ..."]
            SvcAdapters["adapters/services/"]
            AI["adapters/ai/<br/>Claude API"]
            SDKAdapter["adapters/sdk/<br/>core-mqtt-adapter"]
            Web["web/routes/<br/>51 rotas Hono"]
            Config["config/<br/>schema.drizzle, seeds, env"]
        end
    end

    Web --> UC
    UC --> Repos
    UC --> Services
    UC --> Shared
    Repos -. implementado por .-> Persistence
    Services -. implementado por .-> SvcAdapters
    Components -. implementado por .-> CompAdapters
    UC -. usa .-> External
    UC -. usa .-> AI
    CompAdapters -. via MQTT .-> SDKAdapter
```

### Fluxo de uma requisição

1. `HTTP` → rota Hono em `infrastructure/web/routes/`
2. Middleware Logto válida JWT
3. Repositorio Postgres instanciado
4. Use case em `application/use-cases/` executa a regra
5. Eventos publicados no `event-emitter`; serviços disparados pelo `service-registry`
6. Resposta JSON

## Edges, SDK e MQTT

```mermaid theme={null}
flowchart LR
    subgraph CoreSide["Lado Core"]
        CoreAPI["core API"]
        CoreMQTT["core-mqtt-adapter"]
    end

    EMQX{{"EMQX broker"}}

    subgraph HomeEdge["Edge HOME (usuario)"]
        WHome["worker"]
        SDKHome["sdk integrations<br/>(KNX, Zigbee local, Broadlink, ...)"]
        Devices["Devices fisicos"]
    end

    subgraph CloudEdge["Edge CLOUD (Portal)"]
        WCloud["worker"]
        SDKCloud["sdk integrations<br/>(Tuya, LG ThinQ, Spotify, ...)"]
        ClouldAPIs["APIs de fabricantes"]
    end

    CoreAPI --> CoreMQTT
    CoreMQTT <--> EMQX
    EMQX <--> WHome
    EMQX <--> WCloud
    WHome --> SDKHome --> Devices
    WCloud --> SDKCloud --> ClouldAPIs
```

**Tópicos MQTT relevantes:**

* `portal/automation/manual_trigger` — disparar automação
* `portal/automation/lifecycle` — eventos CRUD de automações
* `portal/script/trigger` — executar script
* `portal/events/webhook` — webhook recebido
* `homeassistant/+/+/state` — atualizações de estado de devices

## Padroes transversais

* **Clean Architecture + DDD**: domain isolado de framework; repositorios são interfaces no domain e implementacoes em infrastructure.
* **Event Bus tipado** (`core/shared/event-emitter.ts`): eventos como `User.Created`, `ConfigEntry.Created`, `State.Changed`, `Alexa.*`, `mobile_app_notification_action`.
* **Service Registry** (`application/services/service-registry.ts`): handlers nomeados como `integration.domain.service` (ex.: `tuya.light.turn_on`, `script.script.press`).
* **SDK-first para integrações**: novas integrações moram em `packages/sdk/src/integrations/{domain}/` e rodam em um edge — apenas casos especiais (MQTT, Discord, IRRF) ficam no core.

## Referências no código

* Schema do banco: `packages/core/src/infrastructure/config/schema.drizzle.ts`
* Registro de rotas: `packages/core/src/infrastructure/web/app.ts`
* Factory de entidades Alexa: `packages/core/src/infrastructure/adapters/components/alexa/entity-factory.ts`
* Workspace Deno: `deno.json` (raiz)
* Stack local: `docker-compose.yml`