Arquitetura

Os três produtos do DataSpoc --- Pipe, Lens e ML --- nunca importam código uns dos outros. Eles se comunicam exclusivamente por meio de arquivos Parquet em um bucket compartilhado, seguindo uma convenção rigorosa de diretórios.

O Contrato do Bucket

A estrutura do bucket é a interface entre todos os produtos. Este é o contrato sagrado --- ele nunca deve mudar sem versionamento.

bucket/
  .dataspoc/
    manifest.json                       # Catalog (Pipe writes, Lens reads)
    state/<pipeline>/state.json         # Incremental bookmarks (Pipe only)
    logs/<pipeline>/<timestamp>.json    # Execution logs (Pipe only)
  raw/<source>/<table>/                 # Raw data (Pipe writes)
    dt=YYYY-MM-DD/
      *.parquet
  curated/<domain>/<table>/             # Cleaned data (Pipe transforms)
    dt=YYYY-MM-DD/
      *.parquet
  gold/<domain>/<table>/                # Analyst aggregations (Lens transforms)
    *.parquet
  ml/models/<model>/                    # ML artifacts (ML writes, Lens reads)
    model.pkl
    features.json
    metrics.json
  ml/predictions/<model>/              # ML predictions (ML writes, Lens reads)
    *.parquet

manifest.json

O manifest é o catálogo de tudo que existe no bucket. O Pipe o atualiza em cada execução. O Lens o lê para descobrir tabelas, schemas e partições. O ML o lê para encontrar dados de treino.

Camadas do Data Lake

Camada	Quem escreve	Quem lê	Ferramenta
Raw	Data Engineers	Data Engineers	Pipe (ingestão)
Curated	Data Engineers	Analistas	Pipe (transformação)
Gold	Analistas	Todos	Lens (transformações SQL)
ML Models	Cientistas de Dados	DS, API	ML (treino)
ML Predictions	Cientistas de Dados	Analistas	ML (predição), Lens (consulta)

Raw

Pipe grava os dados brutos exatamente como extraídos da fonte. Um diretório por fonte, um subdiretório por tabela, particionado por data.

Curated

As transformações do Pipe limpam e normalizam os dados brutos. Deduplicação, conversão de tipos, tratamento de nulos. Organizado por domínio de negócio ao invés de sistema de origem.

Gold

As transformações do Lens criam agregações prontas para análise. Resumos de receita, tabelas de KPIs, feeds para dashboards. Acessível para todos na organização.

ML

ML lê das camadas curated ou gold, treina modelos e grava artefatos e predições de volta no bucket. O Lens pode então consultar as predições como qualquer outra tabela.

Controle de Acesso

O DataSpoc nunca implementa autenticação. O controle de acesso é feito inteiramente pelo IAM da nuvem.

Bucket	Acesso	Usuários
s3://company-bronze	Somente DE	Data Engineers
s3://company-finance	Time de Finanças	Analistas, CFO
s3://company-hr	Time de RH	Analistas de RH
s3://company-product	Time de Produto	PMs, Analistas de Produto

Um bucket por perímetro de permissão. Seu provedor de nuvem garante quem pode ler e escrever.

Regras Entre Produtos

Essas regras garantem que os produtos permaneçam desacoplados e que o contrato do bucket seja o único ponto de integração:

1. Pipe nunca importa código do Lens ou ML --- comunicação é apenas via bucket
2. Lens nunca importa código do Pipe ou ML --- lê o bucket, chama ML via subprocess
3. ML nunca importa código do Pipe ou Lens --- lê e escreve Parquet no bucket
4. Platform nunca importa código do Pipe, Lens ou ML --- chama ML via subprocess
5. Todas as mensagens da CLI em inglês
6. Todos os repos usam Python 3.10+, Typer, Pydantic, pytest, uv
7. Nenhum segredo nos repos --- variáveis de ambiente ou IAM da nuvem apenas