Ir para o conteúdo

mindflow v0.1 — Fundação

Status: ✅ Selada · Data: 2026-06-20 · Sessões: 4 + bug fixes

A versão 0.1 estabeleceu a base do mindflow: um ambiente limpo (Chat + Notas + Histórico) construído com TDD desde o primeiro commit, partindo do zero após o brisa-core crescer demais.

1. Contexto e Decisão

  • O brisa-core acumulou complexidade ao longo do tempo: 32 endpoints, generator.py com 626 linhas, index.html com 1.411 linhas — difícil de navegar, entender e evoluir
  • O fluxo de dados estava opaco: features empilhadas sem clareza de responsabilidade
  • Decisão: recomeçar limpo em /workspace/mindflow/, preservando apenas o backend útil (ContextStore + VectorStore)
  • Branch de backup criada no brisa-core: backup/v0.0.x-full-mural — nada foi perdido, apenas deixado de lado

"Funciona" não é suficiente — clareza de fluxo é mais importante que features.

2. O que foi planejado (escopo da versão)

mindmap
  root((mindflow v0.1))
    Fundação técnica
      Context layer
        VectorStore
        Embeddings Gemini
        ContextStore SQLite
      API layer
        5 endpoints
        Auth token+cookie
        FastAPI limpo
    Produto
      Chat com Brisa
      Captura de Notas
      Histórico cronológico
    Infraestrutura
      Container Docker
      HTTPS via Traefik
      Bot Telegram
    Qualidade
      TDD 61 testes
      Playbook revisão
      Changelog versionado

3. Como foi implementado (timeline)

timeline
    title Sessões de implementação — v0.1
    Sessão 1 : Context layer
             : embeddings.py, vector_store.py
             : reindex.py, auto_index.py
             : 47 testes verdes
    Sessão 2 : API layer
             : server.py com 6 endpoints
             : auth token+cookie
             : 61 testes verdes
    Sessão 3 : Frontend
             : Chat + Notas + Histórico
             : 220 linhas total
             : Container rodando
    Sessão 4 : Bot Telegram
             : Migrado do brisa-core
             : Container brisa parado
    Bug fixes : Sessões 4-5
              : 7 bugs corrigidos
              : Gemini embeddings reais
              : Token e sessão ajustados

4. Arquitetura implementada

flowchart LR
    subgraph ENTRADA["Entrada"]
        WEB["💬 Chat Web"]
        NOTAS["📝 Notas Web"]
        TG["📱 Telegram"]
    end

    subgraph CORE["Core (mindflow)"]
        CS["ContextStore\nSQLite\n/data/brisa.db"]
        VS["VectorStore\nsqlite-vec\nGemini embeddings"]
        API["FastAPI\n6 endpoints"]
    end

    subgraph SAIDA["Saída"]
        CHAT["Resposta\ncom contexto"]
        TL["Timeline\ncronológica"]
    end

    WEB & NOTAS & TG --> API
    API --> CS & VS
    CS & VS --> CHAT
    CS --> TL

5. O que ficou de fora (deliberadamente)

O corte foi intencional — cada item abaixo foi avaliado e descartado:

  • ❌ generator.py (626 linhas) — render monolítico sem separação de responsabilidade
  • ❌ Mapa / Nexus / Flows — complexidade prematura, valor não comprovado
  • ❌ 10 endpoints de flow — zero valor no MVP
  • ❌ Copa parser, agenda parser, schedulers — escopo de produto diferente
  • ❌ LangGraph / LangChain — overkill para 3 rotinas simples

Por quê cortar: cada feature removida é uma superfície a menos de manutenção. O v0.1 precisava ser entendível de ponta a ponta em uma leitura.

6. Métricas da versão

Métrica Valor
Testes 61/61 verdes
Linhas de frontend 220 (HTML + CSS + JS)
Endpoints 6
Sessões de TDD 4 + bug fixes
Containers eliminados brisa-mural + brisa + stronda-cup-db
Bugs corrigidos 7

7. Decisões arquiteturais (ADRs)

ADR-001: Novo repo em vez de refatoração

  • Decisão: começar do zero em /workspace/mindflow/
  • Motivo: brisa-core com acúmulo de anos, difícil de entender o fluxo completo
  • Trade-off: reconstruir o que funcionava × clareza para crescer

ADR-002: todo.md fora do mindflow v0.1

  • Decisão: mindflow não usa todo.md — apenas ContextStore
  • Motivo: simplificar o MVP; todo.md é gerenciado separadamente pelo bot Brisa
  • Trade-off: perder gestão de tasks no chat × ganhar simplicidade no core

ADR-003: Bot Telegram no mesmo processo

  • Decisão: bot Telegram roda como daemon thread no uvicorn
  • Motivo: evitar segundo container; compartilha store/vstore nativamente
  • Trade-off: restart do web = restart do bot × infraestrutura simples e sem overhead

ADR-004: DeepSeek em vez de Claude direto

  • Decisão: usar DeepSeek via compatibilidade OpenAI para o chat
  • Motivo: configuração existente na infra, custo menor por token
  • Trade-off: menos capacidades de raciocínio × compatível com a infra existente

8. O que vem na v0.2

Escopo aprovado para a próxima versão:

  • Quick Action Cards — Briefing, Setup, Ajudar com brisa (atalhos no frontend)
  • Fix BUG-SESSION-001 — localStorage token perdido ao fechar o browser
  • Streaming SSE — respostas do chat chegam em tempo real, sem esperar o fim
  • Bot Telegram com tool_use — get_todo, set_context como ferramentas do bot
  • CI/CD GitHub Actions — testes rodando automaticamente a cada push