Guia do repositório
Esta página é uma tradução automática da página em inglês, que prevalece. Machine-translated from the English page, which is authoritative.
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.
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 |
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 |
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 |
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) |
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) |
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 |
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 é 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.
| 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) |
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 |
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.
Ordem de leitura para quem está começando a contribuir
- O README e a visão geral do sistema: a superfície do produto e o formato do sistema.
server/operations/registry.py: o registro de wire-ops que todo transporte percorre.server/main.py, o lifespan: como as migrações, os workers e os transportes são conectados.- O grupo de ops em
server/<domain>/api/ops*.pyreferente ao que você está alterando, depois o handler correspondente emserver/<domain>/app/e os repositórios emserver/<domain>/store/que ele chama. schemas/schema.sqlpara as tabelas que ele lê e escreve.AGENTS.mde.claude/rules/: as convenções e suas justificativas.
Convenções que não são óbvias
O CONTRIBUTING.md as lista, e o 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) | 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) |
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).