# 01 — Arquitetura do Sistema (G-ART / fcp-mcp-server)

> Referência canônica de como o sistema está dividido e implementado. Leia este
> documento antes de qualquer mudança de código.

## 1. Visão de cima (camadas)

O sistema é um **servidor MCP em Python** que lê/analisa/reescreve arquivos
**FCPXML** do Final Cut Pro. Há **três camadas** bem separadas:

```
┌─────────────────────────────────────────────────────────────┐
│  admin/  — Aplicações complementares (fora do MCP)          │
│    models_api.py    API (FastAPI) p/ gerenciar modelos      │
│    models_gui.py    UI desktop (Flet) p/ gerenciar modelos  │
│    graphify.sh/.md  Pipeline de graphify do código          │
├─────────────────────────────────────────────────────────────┤
│  server.py  — CAMADA MCP / TRANSPORTE (NÃO tem lógica)      │
│    62 tools, handlers, prompts, resources, dispatch         │
│    Só valida entrada/saída e traduz JSON-RPC → chamadas     │
├─────────────────────────────────────────────────────────────┤
│  fcpxml/  — "ENGINE" = NÚCLEO PURO Python (desacoplado)     │
│    Não conhece MCP nem argumentos de tool.                  │
│    Trabalha com objetos Python e XML.                       │
│    É o foco / onde quase tudo mora.                         │
└─────────────────────────────────────────────────────────────┘
```

**Regra de arquitetura:** `server.py` NUNCA implementa lógica de timeline —
ele delega ao `fcpxml/`. Tudo em `fcpxml/` é testável isoladamente (1032 testes).

## 2. Regras transversais (convenções em todo o código)

| Conceito | Regra |
|----------|-------|
| **Tempo** | `TimeValue` fração racional `"600/2400s"`. Nunca use float p/ tempo. |
| **I/O paths** | Sempre via helpers `_validate_filepath` / `_validate_output_path` (sandbox). |
| **Nome de saída** | Nunca sobrescrever original: `output_<suffix>.fcpxml`. |
| **Segurança XML** | Sempre `defusedxml` (via `safe_xml.py`). Nunca `xml.etree` direto. |
| **Deps opcionais** | `librosa`/`ffmpeg`/`huggingface_hub` importados **lazy**, degradam com `None`. |
| **Lint** | `ruff check . --exclude docs/` — zero erros. |
| **Validação pós-correção** | `./Engine/run_after_fix.sh` SEMPRE após cada correção. |

## 3. Fluxo de um request (round-trip)

```
Cliente MCP (Claude)
      │  JSON-RPC (stdio)
      ▼
server.py ── dispatcher (TOOL_HANDLERS)
      │  valida path, parseia projeto, chama engine
      ▼
fcpxml/parser.py      XML → objetos
fcpxml/writer.py      edita / grava
fcpxml/rough_cut.py   gera novas timelines
fcpxml/export.py      cross-NLE
      ▼
output_<suffix>.fcpxml   (original intocado)
      ▼
Final Cut Pro: File → Import → XML   (ou push_to_fcp, sem cliques)
```

## 4. Dual-mode: XML + Live

O sistema opera em **dois modos complementares**:

- **Modo XML (principal):** exporta FCPXML, processa como dados, reimporta.
  Roda fora do FCP. Nenhuma API privada.
- **Modo Live (`fcpxml/live.py`):** *push* do FCPXML direto p/ o FCP em
  execução via Apple events oficiais (`Open Document`), com `import-options`.
  Leitura de bibliotecas via AppleScript read-only.

**Assimetria estrutural:** import é scriptable, mas a Apple não oferece export
programático — round-trips voltam pelas ferramentas XML.

## 5. Onde está cada responsabilidade

| Responsabilidade | Fica em |
|------------------|---------|
| Modelos de dados (tempo, clips, markers) | `fcpxml/models.py` |
| Parse FCPXML → objetos | `fcpxml/parser.py` |
| Editing/escrita (modifier + writer) | `fcpxml/writer.py` |
| Geração de timeline nova | `fcpxml/rough_cut.py` |
| Comparação de timelines | `fcpxml/diff.py` |
| Export cross-NLE (Resolve, FCP7) | `fcpxml/export.py` |
| Inteligência de mídia (silêncio/beats) | `fcpxml/media_intel.py` |
| Transcrição Whisper local | `fcpxml/transcribe.py` |
| Gestão de modelos Whisper | `fcpxml/model_manager.py` |
| Templates de timeline | `fcpxml/templates.py` |
| Controle Live do FCP | `fcpxml/live.py` |
| Segurança XML (`defusedxml`, `serialize_xml`) | `fcpxml/safe_xml.py` |
| Validação contra DTDs da Apple | `fcpxml/dtd.py` |
| Transporte MCP (62 tools) | `server.py` |

## 6. Mapa de dependências (você está aqui se for mexer no X → quem tocar)

```
server.py ──► fcpxml/parser, writer, rough_cut, export, diff,
               media_intel, transcribe, templates, live, dtd
admin/models_gui.py ──► fcpxml/media_intel, model_manager,
                        parser, transcribe
admin/models_api.py  ──► fcpxml/model_manager
fcpxml/writer.py     ──► fcpxml/models, safe_xml, dtd
fcpxml/__init__.py   ──► reexporta a API pública
```

> Se você cria uma **nova ferramenta MCP**, o trabalho principal é em `fcpxml/`
> (função pura + testes). O handler em `server.py` fica fino: validação de
> caminho → `_parse_project` → chama a função → `_text_result`.