---
title: "Guia do repositório"
---

<!-- i18n: source=docs/development/repository-guide.md blob=680d8d038e278f6e630e4556f475452ba591d298 model=claude-sonnet-5-5 -->
> Esta página é uma tradução automática da [página em inglês](https://github.com/ClickHouse/loom/blob/main/docs/development/repository-guide.md), que prevalece.
> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/development/repository-guide.md), which is authoritative.

<a id="repository-guide"></a>

O que cada diretório de nível superior contém, onde cada responsabilidade fica dentro de `server/`, a ordem em que ler o código e as convenções sem as quais um pull request é reprovado.

<a id="top-level-layout"></a>

## Estrutura de nível superior

| Caminho                                                                                                                                                      | Conteúdo                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `server/`                                                                                                                                                    | o servidor FastAPI: pacotes de domínio (memory, code, tracker, …), o registro de operações, workers, transportes, CLI, configurações                                                                                                                                                                                                                                                     |
| `extractor/`                                                                                                                                                 | o serviço extrator de referência (`loom_extractor/`): detecção de formato e os parsers de documentos, executados fora do servidor; sua imagem (`Dockerfile`, publicada como `ghcr.io/clickhouse/loom-extractor`) e seu lock (`uv.lock`); veja [extração de documentos](https://github.com/ClickHouse/loom/blob/main/docs/architecture/document-extraction.md)                              |
| `sdk/python/`                                                                                                                                                | o SDK Python, publicado como `clickhouse-loom` (`sdk/python/loom/`)                                                                                                                                                                                                                                                                                                                      |
| `sdk/typescript/`                                                                                                                                            | o SDK TypeScript, publicado como `@clickhouse/loom` (`sdk/typescript/src/`)                                                                                                                                                                                                                                                                                                              |
| `frontend/`                                                                                                                                                  | o painel React servido em `/` (Vite + Tailwind); `src/`, specs do Playwright em `e2e/`, `scripts/bundle_budget.mjs`                                                                                                                                                                                                                                                                      |
| `schemas/`                                                                                                                                                   | `migrations/` (SQL numerado), `schema.sql` (formato atual gerado), `otel/` (tabelas OTel do ClickStack), `ops/` (SQL executado manualmente); veja [`schemas/README.md`](https://github.com/ClickHouse/loom/blob/main/schemas/README.md)                                                                                                                                                   |
| `dev/`                                                                                                                                                       | stacks do compose, scripts de operação (`loom_ingest.py`, `loom_init.py`, `onboard_tenant.py`, backup e restauração, `verify_audit_chain.py`), `ci_start_clickhouse.sh`, `redeploy_preflight.sh`                                                                                                                                                                                         |
| `deploy/`                                                                                                                                                    | configuração do servidor ClickHouse (`clickhouse-config/`), o modelo Lemmagen3 (`lemmagen3/`), o proxy blue/green (`proxy/`), o chart Helm (`helm/`), o perfil AppArmor do sandbox de jobs de repositório (`apparmor/`), o template de env standalone (`standalone/`), o CronJob agendado de cópia de namespace (`okf-sync/`), painéis (`dashboards/`, `hyperdx_dashboards.md`, `clickstack_sources.sh`) |
| `bench/`                                                                                                                                                     | harnesses e gates de benchmark, seus fixtures (`fixtures/`), datasets, rubricas, avaliações de aceitação e de skills; veja [benchmarks de desempenho](https://github.com/ClickHouse/loom/blob/main/docs/benchmarks/overview.md)                                                                                                                                                           |
| `integrations/`                                                                                                                                              | integrações de clientes: os plugins do Claude Code e do Codex, os hooks do Cline, o grep shim, hooks do Cursor e de transcrição genéricos, o gate de CI do OKF                                                                                                                                                                                                                            |
| `skills/`                                                                                                                                                    | as Agent Skills independentes: `loom-code` e `loom` (o guia do agente que a imagem do servidor inclui e que `mentor.guide` serve)                                                                                                                                                                                                                                                        |
| `scripts/`                                                                                                                                                   | `codegen/` (geradores), `gates/` (ratchets e proteções de CI), `ops/` (ferramentas de operação), `scip_harness/` (produtores da camada do compilador), `docs_site/` (o hook do site de documentação, a substituição de tema, o builder fixado e o envio ao IndexNow), `i18n/` (o gerador de traduções e sua verificação de atualização)                                                    |
| `tests/`                                                                                                                                                     | `unit/`, `integration/`, `analyzer/`, `code_lanes/`, `fixtures/` (abaixo)                                                                                                                                                                                                                                                                                                                |
| `examples/`                                                                                                                                                  | exemplos de integração executáveis (`claude_agent_loop.py`, `ledger_run.py`, `log_conversation.py`, `onboarding_walkthrough.py`) e o starter de curso que um professor copia para um repositório próprio (`course-starter/`, [ensino](https://github.com/ClickHouse/loom/blob/main/docs/guides/teaching.md#hand-out-the-labs-as-an-assignment))                                           |
| `i18n/`                                                                                                                                                      | traduções automáticas do README, do quickstart e das páginas de casos de uso, uma pasta por idioma em `LANGUAGES`; geradas por `scripts/i18n/translate.py` (`.github/workflows/i18n.yml`), nunca editadas manualmente                                                                                                                                                                     |
| `docs/`                                                                                                                                                      | esta documentação; `mkdocs.yml` e `scripts/docs_site/` a compilam como o site de documentação (`.github/workflows/docs-site.yml`)                                                                                                                                                                                                                                                        |
| `.github/`                                                                                                                                                   | workflows de CI, release e varredura (`workflows/`), templates de issues e pull requests, e `social-preview.png`, a imagem enviada em Settings → General → Social preview (o GitHub lê apenas a cópia enviada)                                                                                                                                                                           |
| `.devcontainer/`                                                                                                                                             | o teste no GitHub Codespaces: um dev container que instala a última versão com o instalador e conecta o Claude Code; não é um ambiente de desenvolvimento ([guia de início rápido](/docs/pt-BR/getting-started/quickstart#try-it-in-github-codespaces))                                                                                                                                        |
| `Dockerfile`, `Makefile`, `redeploy.sh`, `pyproject.toml`, `uv.lock`                                                                                         | a imagem do servidor, o executor de tarefas, o script de deploy blue/green, o pacote do servidor e seu arquivo de lock                                                                                                                                                                                                                                                                   |
| `server.json`, `context7.json`, `CITATION.cff`, `gemini-extension.json`, `.claude-plugin/`, `.cursor-plugin/`, `plugin.json`, `mcp.json`, `.agents/plugins/` | a listagem no MCP Registry, a configuração do índice de documentação, a citação que o GitHub mostra como "Cite this repository", o manifesto da extensão do Gemini CLI, o marketplace do Claude Code com o manifesto da skill `loom-code`, o marketplace e plugin do Cursor, o pacote Agent Plugins que o GitHub Copilot CLI instala, o marketplace do Codex                              |
| `llms-install.md`                                                                                                                                            | os passos que um agente de código segue para instalar o Loom e adicioná-lo como servidor MCP                                                                                                                                                                                                                                                                                             |
| `AGENTS.md`, `CLAUDE.md`                                                                                                                                     | as instruções que todo agente de código lê; `CLAUDE.md` importa `AGENTS.md`                                                                                                                                                                                                                                                                                                              |
| `.claude/`, `.agents/skills/`                                                                                                                                | as skills dos agentes, regras com escopo de caminho, o subagente revisor somente leitura e seu hook, e as configurações de permissão do projeto; `.agents/skills/` vincula cada skill para o Codex                                                                                                                                                                                       |

<a id="inside-server"></a>

## Dentro de server/

`server/` é organizado por domínio. Uma requisição entra por um transporte, é despachada pelo registro de operações para um handler no `app/` de um domínio, que executa a lógica pura de `domain/` e lê e escreve por meio dos repositórios em `store/`, que guardam o SQL do domínio. O [layout do servidor](/docs/pt-BR/architecture/server-layout) é o mapa completo, com as regras de importação que um teste de contrato impõe; o caminho da requisição está na [visão geral do sistema](https://github.com/ClickHouse/loom/blob/main/docs/architecture/system-overview.md).

| Pacote / módulo                                                                                         | Papel                                                                                                                                                                                                                                                                                                                                         |
| ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `memory/`, `code/`, `tracker/`, `knowledge/`, `erasure/`, `tasks/`, `identity/`, `insights/`            | os pacotes de domínio; cada um contém até cinco camadas: `api/` (modelos de wire `models*.py` e listas de `Operation` em `ops*.py`), `app/` (handlers e orquestração), `domain/` (lógica pura), `store/` (repositórios ClickHouse e construtores de linhas; `memory/store/rows.py` contém os construtores de linhas de versão), `workers/` (loops em segundo plano) |
| `operations/`                                                                                           | o núcleo do registro: `Operation` e `Role` (`base.py`); `registry.py` importa o grupo de operações de cada domínio e monta `ALL_OPERATIONS` e `OPERATIONS_BY_NAME`; `toolsets.py`, projeção de leitura, o censo de alcance                                                                                                                      |
| `transport/`                                                                                            | HTTP (`http.py`) e MCP (`mcp.py` com `mcp_schemas`, `mcp_config`, `mcp_tools`, `mcp_identity`), feedback de argumentos, limites de corpo                                                                                                                                                                                                      |
| `workers/`                                                                                              | o registro de workers (`registry.py`, `_WORKERS`) e o supervisor (`supervisor.py`) que o executa; cada loop fica no `workers/` do seu domínio                                                                                                                                                                                                  |
| `settings/`                                                                                             | todas as configurações em `catalog.py`, uma seção por área, compostas em `Settings`                                                                                                                                                                                                                                                           |
| `auth/`                                                                                                 | emissão e verificação de JWT, papéis e concessões, login, OIDC, autocadastro, revogação                                                                                                                                                                                                                                                       |
| `embedding/`, `llm/`                                                                                    | superfícies de provedores plugáveis (OpenAI, Anthropic, Gemini, local, fake), caches e fallback                                                                                                                                                                                                                                               |
| `observability/`                                                                                        | o emissor do ledger, log de auditoria, contabilização de custos e orçamentos, métricas e spans OTel, a lista `problems` que `/v1/health` reporta                                                                                                                                                                                              |
| `clients/`                                                                                              | clientes HTTP para serviços externos (o pool compartilhado de provedores, GitHub)                                                                                                                                                                                                                                                             |
| `storage/`                                                                                              | composição de TTL por tabela                                                                                                                                                                                                                                                                                                                  |
| `cli/`                                                                                                  | a árvore de comandos `loom` (`app.py` a monta)                                                                                                                                                                                                                                                                                                |
| `main.py`, `boot.py`, `health.py`, `wiring.py`                                                          | o app FastAPI e seu lifespan (workers, transportes), as etapas de boot e desligamento (migração no boot, snapshot de revogação), `/v1/health` e `wire()`                                                                                                                                                                                      |
| `core/ch.py`                                                                                            | o cliente ClickHouse, pooling e atribuição de queries (`set_query_tag`)                                                                                                                                                                                                                                                                       |
| `core/errors.py`                                                                                        | erros tipados (subclasses de `LoomServerError`) e seu status HTTP                                                                                                                                                                                                                                                                             |
| `core/ratelimit.py`, `core/ratelimit_shared.py`, `core/idempotency.py`, `memory/app/blacklist_guard.py` | proteções do caminho da requisição                                                                                                                                                                                                                                                                                                            |
| `core/schema/`                                                                                          | o executor de migrações (`migrate.py`) e seu lock entre contêineres (`migrate_lease.py`), e as reescritas de schema que o executor e as ferramentas de rebuild compartilham (`table_rebuild.py`, `vector_codec_ddl.py`)                                                                                                                        |

<a id="inside-tests"></a>

## Dentro de tests/

| Caminho              | Conteúdo                                                                                                                                                       |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tests/unit/`        | testes rápidos que não precisam de ClickHouse; `snapshots/` (árvore e ajuda da CLI, registro de workers, API pública do SDK), `fixtures/`, helpers compartilhados |
| `tests/integration/` | testes contra um servidor em execução e o ClickHouse (`tests/conftest.py` e `tests/integration/conftest.py` fazem a ligação), incluindo a sonda de vazamento entre principals |
| `tests/analyzer/`    | o corpus de instruções: os formatos de cada construtor de SQL passando por `EXPLAIN QUERY TREE` em tabelas vazias migradas; veja o [README](https://github.com/ClickHouse/loom/blob/main/tests/analyzer/README.md) |
| `tests/code_lanes/`  | o corpus das lanes de SQL e shell: o que o índice de código deriva de `tests/fixtures/code_lanes/`, comparado com uma expectativa commitada                    |
| `tests/fixtures/`    | entradas compartilhadas entre as suítes                                                                                                                        |

Como cada suíte é executada, ignorada e usada como critério no CI está em [testes](https://github.com/ClickHouse/loom/blob/main/docs/development/testing.md).

<a id="reading-order-for-a-new-contributor"></a>

## Ordem de leitura para quem está começando a contribuir

1. O [README](https://github.com/ClickHouse/loom/blob/main/README.md) e a [visão geral do sistema](https://github.com/ClickHouse/loom/blob/main/docs/architecture/system-overview.md):
   a superfície do produto e o formato do sistema.
2. [`server/operations/registry.py`](https://github.com/ClickHouse/loom/blob/main/server/operations/registry.py): o registro
   de wire-ops que todo transporte percorre.
3. `server/main.py`, o lifespan: como as migrações, os workers e os transportes são conectados.
4. O grupo de ops em `server/<domain>/api/ops*.py` referente ao que você está alterando, depois
   o handler correspondente em `server/<domain>/app/` e os repositórios em `server/<domain>/store/`
   que ele chama.
5. [`schemas/schema.sql`](https://github.com/ClickHouse/loom/blob/main/schemas/schema.sql) para as tabelas que ele lê e escreve.
6. [`AGENTS.md`](https://github.com/ClickHouse/loom/blob/main/AGENTS.md) e `.claude/rules/`: as convenções e suas justificativas.

<a id="conventions-that-are-not-obvious"></a>

## Convenções que não são óbvias

O [CONTRIBUTING.md](https://github.com/ClickHouse/loom/blob/main/CONTRIBUTING.md#conventions-that-arent-obvious) as lista, e o [`AGENTS.md`](https://github.com/ClickHouse/loom/blob/main/AGENTS.md), junto com as regras em `.claude/rules/`, explica os motivos. Estes testes e verificações as fazem valer:

| Verificação                                                                      | Garante                                                  |
| -------------------------------------------------------------------------------- | -------------------------------------------------------- |
| tabelas de SDK geradas, censo de alcance ([geração de código](https://github.com/ClickHouse/loom/blob/main/docs/development/code-generation.md))       | ops são linhas do registro                               |
| `tests/integration/test_cross_principal_leakage.py`                              | ops de id em toda a organização ocultam uma linha de outro principal como `found=False` |
| `test_memory_versions_schema.py`                                                 | as colunas de `loom.memory` são espelhadas em `loom.memory_versions` |
| `test_migrations_additive.py`, o checksum do ledger ([migrações](https://github.com/ClickHouse/loom/blob/main/docs/development/migrations.md)) | migrações são aditivas e nunca são editadas              |
| `test_every_table_is_classified.py`                                              | toda tabela é classificada para apagamento               |
| `test_settings_attribute_access.py`, `test_settings_reference.py`                | configurações são lidas como `settings.<field>`, e a referência está atualizada |
| `test_worker_registry_snapshot.py`, `test_worker_registry_parity.py`             | workers são linhas do registro                           |
| ruff `BLE001`                                                                    | um except genérico explica o motivo                      |
| `scripts/gates/function_length_gate.py`                                          | nenhuma função cresce além de sua linha de base          |
| `tests/unit/test_public_copy.py`                                                 | o texto do repositório é neutro quanto ao produto        |

Os formatos fundamentais (ClickHouse como único mecanismo, a tupla de identidade, a auditoria de hash de conteúdo por linha, as cinco operações de revisão de crenças) exigem uma justificativa de design no pull request e uma atualização da página de arquitetura correspondente ([mudanças relevantes](https://github.com/ClickHouse/loom/blob/main/CONTRIBUTING.md#material-changes)).

<a id="related"></a>

## Relacionados

- [Desenvolvimento local](https://github.com/ClickHouse/loom/blob/main/docs/development/local-development.md), [testes](https://github.com/ClickHouse/loom/blob/main/docs/development/testing.md),
  [geração de código](https://github.com/ClickHouse/loom/blob/main/docs/development/code-generation.md)
- [Adicionando uma operação](https://github.com/ClickHouse/loom/blob/main/docs/development/adding-an-operation.md), [adicionando um worker](https://github.com/ClickHouse/loom/blob/main/docs/development/adding-a-worker.md), [adicionando uma tabela](https://github.com/ClickHouse/loom/blob/main/docs/development/adding-a-table.md), [adicionando suporte a uma linguagem](https://github.com/ClickHouse/loom/blob/main/docs/development/adding-language-support.md), [estendendo o Loom](https://github.com/ClickHouse/loom/blob/main/docs/development/extending-loom.md)
