Arquitetura

Visão geral

flowchart TB
    subgraph Core["Core"]
        A[Artifact Markdown + Frontmatter]
        V[Validação]
        C[Context Rules]
        M[Metadata]
    end
    
    subgraph Publishing["Publishing"]
        P1[Adapter Codex]
        P2[Adapter Claude]
        P3[Adapter OpenCode]
        P4[install / sync / upgrade / doctor]
    end
    
    subgraph Operation["Operation"]
        O1[CLI Commands]
        O2[Project Context]
        O3[Feature Context]
        O4[Session Context]
        O5[Integration Context]
    end
    
    Core --> Publishing
    Publishing --> Operation
    
    style Core fill:#1a2740,stroke:#7C3AED,color:#eef6ff
    style Publishing fill:#17233b,stroke:#2563EB,color:#eef6ff
    style Operation fill:#1a2740,stroke:#22D3EE,color:#eef6ff

Camadas

Core

• Artefatos Markdown com frontmatter
• Validação de contratos
• Regras de contexto
• Metadados de execução

Publishing

• Adapters por host
• Materialização de arquivos nativos
• install, sync, upgrade, doctor

Operation

• Comandos CLI
• Contexto de projeto, feature, sessão e integrações
• Workflow status e retomada de sessões

Módulos do repositório

Code Context (src/lib/code-context/)

Descoberta multi-linguagem, providers, graph builder, query API e resolução de dependências.

Módulo	Descrição
schema.ts	Tipos do CodeContextDocument (módulos, símbolos, relações)
graph-schema.ts	Tipos do KnowledgeGraph (KnowledgeNode, KnowledgeEdge)
manager.ts	Orquestrador do refresh-code-context
providers/	7 providers de linguagem + database.ts (Prisma, Drizzle, TypeORM, SQL)
graph-builder.ts	Construtor do Knowledge Graph
resolve-deps.ts	Cross-module dependency resolver
graph-query.ts	API de consulta (neighborhood, path, dependentsOf)
feature-impact.ts	Mapeamento feature→código com graph traversal + fallback token-matching
storage.ts	Persistência de code-context.json e knowledge-graph.json

Estrutura de diretórios

src/
├── lib/
│   ├── code-context/       # Contexto de código
│   └── ...                 # Contratos, helpers e fluxos compartilhados
├── hosts/                  # Adapters e publicação por host
└── validation/             # Validação de packs

packs/                      # Artefatos publicados (fonte)
.looply/
├── managed/packs/          # Packs gerenciados (runtime)
├── custom/
│   ├── features/           # Features em progresso
│   └── integrations/       # Integrações configuradas
└── state/                  # Estado operacional

platform/contracts/         # Contratos formais (agent, task, workflow, etc.)
tools/                      # Helpers de descoberta (.NET, Python)
docs-site/                  # Portal de documentação

Fluxo de dados

sequenceDiagram
    participant User as Usuário
    participant CLI as looply CLI
    participant Codebase as Codebase
    participant Pack as Packs/Artifacts
    participant Host as Host (Codex/Claude)
    
    User->>CLI: looply install
    CLI->>Pack: Lê artefatos
    CLI->>Codebase: Extrai contexto
    CLI->>CLI: Constrói Knowledge Graph
    CLI->>Host: Publica skills + comandos
    Host-->>User: /looply:* disponíveis
    
    User->>Host: /looply:story-to-production
    Host->>CLI: workflow-status
    CLI->>CLI: Lê Context Ledger
    CLI-->>Host: Estado atual + próximo passo
    Host->>User: Executa tarefa
    
    loop Cada stage
        Host->>CLI: ledger append "decisão"
        CLI->>CLI: Persiste no Context Ledger
    end