🗓️ ROADMAP CIDADÃO.AI v1.0 - OUTUBRO/NOVEMBRO 2025¶

Objetivo: Finalizar versão 1.0 do sistema até 30 de novembro de 2025 Status Atual: v0.9.7 - Updated with Real Test Metrics (30/10/2025) Meta v1.0: 100% funcional, production-ready, dados reais

✅ MAJOR UPDATE (30/10/2025): Test coverage discovered to be 76.29% (not 44% as previously claimed). Total of 1,363 tests across 98 files. All 16 agents have comprehensive test coverage. See coverage report for details.

📊 VISÃO GERAL¶

Onde Estamos (30 de outubro - ATUALIZADO)¶

✅ 16/16 agentes implementados (100%)
✅ 10/16 Tier 1 operacionais (62.5%)
✅ 76.29% test coverage (agents) - Nearly at goal! 🎯
✅ 1,363 total tests - Comprehensive coverage!
✅ 16/16 agents tested (100%) - All agents have tests!
✅ 266+ endpoints REST
✅ Deployed on Railway (production since 07/10)
✅ PostgreSQL + Redis operational
⚠️ Portal da Transparência: Real data integrated (with API key)
⚠️ Céuci & Abaporu: Need coverage boost
⚠️ ML models: Training pending

Onde Queremos Chegar (30 de novembro)¶

✅ 18/18 agentes operacionais (100%)
✅ Todos os agentes com dados reais
✅ 2-3 ML models treinados e em produção
✅ Database persistente (Supabase)
✅ Redis em produção
✅ CI/CD pipeline completo
✅ Documentação completa
✅ Portal da Transparência: alternativas implementadas

🎯 OUTUBRO 2025 (4 SEMANAS)¶

Foco: Completar funcionalidades críticas e resolver bloqueios de dados

SEMANA 1 (14-20 OUT) - "Data Liberation Week"¶

Objetivo: Resolver bloqueios de dados e integrar APIs reais

🔥 Prioridade CRÍTICA¶

1. Resolver Bloqueio Portal da Transparência - Tarefa: Investigar alternativas para os 78% de endpoints bloqueados - Opções: - [ ] Solicitar API key de tier superior (CGU) - [ ] Implementar crawler autorizado (robots.txt compliant) - [ ] Expandir uso de TCE APIs (já temos 6) - [ ] Usar mais CKAN portals (já temos 5) - Entregável: Acesso a pelo menos 50% dos endpoints bloqueados - Tempo estimado: 16 horas - Responsável: Backend team

2. Integrar Dandara com APIs Federais Reais - APIs a integrar: - [ ] IBGE API - Dados demográficos e censo - [ ] DataSUS API - Indicadores de saúde - [ ] INEP API - Dados educacionais - [ ] MDS API - Programas sociais (Bolsa Família, etc.) - [ ] RAIS API - Dados trabalhistas - [ ] PNAD API - Pesquisa Nacional por Amostra - Entregável: Dandara 100% operacional com dados reais - Tempo estimado: 20 horas - Arquivo: src/agents/dandara.py - Tests: tests/unit/agents/test_dandara.py

3. Consolidar Implementações de Chat - Problema: 5 versões diferentes (chat.py, chat_simple.py, chat_stable.py, etc.) - Tarefa: - [ ] Analisar performance de cada versão - [ ] Escolher a mais estável - [ ] Migrar features importantes das outras - [ ] Deletar versões obsoletas - [ ] Atualizar testes - Entregável: 1 única implementação estável - Tempo estimado: 12 horas

📈 Prioridade ALTA¶

4. Consolidar Agentes Niemeyer - Problema: niemeyer.py (2,270 linhas) vs oscar_niemeyer.py (1,224 linhas) - Tarefa: - [ ] Comparar funcionalidades - [ ] Manter oscar_niemeyer.py (mais recente) - [ ] Migrar features úteis de niemeyer.py - [ ] Deletar niemeyer.py - [ ] Atualizar imports - Entregável: 1 único agente de visualização - Tempo estimado: 8 horas

Milestone Semana 1: 🎯 Data Foundation Complete - ✅ Dandara 100% operacional - ✅ Portal da Transparência >50% acessível - ✅ Chat consolidado - ✅ Niemeyer consolidado

SEMANA 2 (21-27 OUT) - "Infrastructure Week"¶

Objetivo: Implementar persistência e infraestrutura de produção

🔥 Prioridade CRÍTICA¶

5. Migrar para PostgreSQL Persistente (Supabase) - Problema: HuggingFace usa in-memory (dados perdidos em restart) - Tarefa: - [ ] Configurar Supabase project - [ ] Criar schema completo (investigations, contracts, users, etc.) - [ ] Implementar migrations com Alembic - [ ] Atualizar src/db/session.py para usar Supabase REST API - [ ] Migrar dados de teste - [ ] Atualizar testes - Entregável: Database persistente funcional - Tempo estimado: 16 horas - Arquivo: src/db/session.py, alembic/versions/

6. Implementar Redis em Produção - Problema: Cache in-memory (performance subótima) - Tarefa: - [ ] Setup Redis Cloud ou Railway Redis - [ ] Configurar connection pooling - [ ] Atualizar cache service para usar Redis - [ ] Implementar cache warming automático - [ ] Configurar TTLs por tipo de dado - [ ] Métricas Prometheus para cache - Entregável: Redis funcional com >70% hit rate - Tempo estimado: 12 horas - Arquivo: src/services/cache_service.py

📈 Prioridade ALTA¶

7. Setup CI/CD Pipeline (GitHub Actions) - Tarefa: - [ ] Criar .github/workflows/ci.yml - [ ] Automated tests on PR - [ ] Automated linting (Black, Ruff, MyPy) - [ ] Coverage report com CodeCov - [ ] Deploy automático para HuggingFace on merge - [ ] Deploy automático para Railway (staging) - Entregável: CI/CD completo - Tempo estimado: 12 horas

8. Re-habilitar TrustedHostMiddleware (Railway) - Problema: Desabilitado por incompatibilidade com HF Spaces - Tarefa: - [ ] Criar configuração condicional (HF vs Railway) - [ ] Configurar allowed_hosts para Railway - [ ] Testar em staging - Entregável: Middleware ativo em Railway - Tempo estimado: 4 horas - Arquivo: src/api/app.py

Milestone Semana 2: 🎯 Infrastructure Ready - ✅ PostgreSQL persistente funcional - ✅ Redis em produção - ✅ CI/CD pipeline completo - ✅ Security hardened

SEMANA 3 (28 OUT - 03 NOV) - "ML Training Week"¶

Objetivo: Treinar e deployar modelos de Machine Learning

🔥 Prioridade CRÍTICA¶

9. Treinar Corruption Detector Model - Objetivo: Substituir Lei de Benford threshold por ML model - Tarefa: - [ ] Coletar dataset de treinamento (contratos históricos) - [ ] Rotular dados (corrupto vs limpo) - pode usar Benford como baseline - [ ] Feature engineering (15 features identificadas por Ceuci) - [ ] Treinar Random Forest Classifier - [ ] Validação cruzada (80/20 split) - [ ] Hyperparameter tuning - [ ] Deploy modelo para Models API - [ ] Integrar com Obaluaiê agent - Entregável: Modelo treinado com >85% accuracy - Tempo estimado: 20 horas - Arquivo: src/ml/corruption_detector.py - Dataset: Usar Portal + TCE data

10. Treinar Anomaly Scorer Model - Objetivo: Melhorar detecção de anomalias do Zumbi - Tarefa: - [ ] Coletar dataset (contratos + anomalias detectadas) - [ ] Treinar Isolation Forest - [ ] Feature importance analysis (SHAP) - [ ] Ajustar thresholds - [ ] Deploy para Models API - [ ] Integrar com Zumbi agent - Entregável: Modelo com >80% precision/recall - Tempo estimado: 16 horas

📈 Prioridade ALTA¶

11. Implementar Explainable AI (XAI) Dashboard - Tarefa: - [ ] Integrar SHAP com modelos treinados - [ ] Criar endpoint /api/v1/ml/explain - [ ] Gerar visualizações de feature importance - [ ] Adicionar explanations aos relatórios - Entregável: Explicações para 100% das previsões ML - Tempo estimado: 12 horas

12. Time Series Forecasting (Ceuci) - Tarefa: - [ ] Treinar Prophet model para previsão de gastos - [ ] Validar com dados históricos - [ ] Integrar com Ceuci agent - [ ] Dashboard de forecasting - Entregável: Previsões com MAPE <20% - Tempo estimado: 12 horas

Milestone Semana 3: 🎯 ML Models Operational - ✅ 2 modelos treinados e em produção - ✅ XAI implementado - ✅ Forecasting funcional - ✅ Models API integrado

SEMANA 4 (04-10 NOV) - "Testing & Quality Week"¶

Objetivo: Aumentar qualidade e cobertura de testes

🔥 Prioridade CRÍTICA¶

13. Expandir Test Coverage para 90% - Atual: 80.5% (1,133 testes) - Meta: 90%+ (adicionar ~200 testes) - Áreas críticas: - [ ] ML models (src/ml/) - [ ] Infrastructure (src/infrastructure/) - [ ] Services (src/services/) - [ ] API routes (src/api/routes/) - Entregável: 90%+ coverage - Tempo estimado: 20 horas

14. Performance Testing Suite - Tarefa: - [ ] Criar benchmarks para todos os agentes - [ ] Load testing (Locust) - [ ] Stress testing (1000+ concurrent users) - [ ] Identificar bottlenecks - [ ] Otimizar queries lentas - Entregável: Performance report - Tempo estimado: 12 horas - Arquivo: tests/performance/

📈 Prioridade ALTA¶

15. Integration Tests End-to-End - Tarefa: - [ ] Complete investigation workflow test - [ ] Multi-agent orchestration test - [ ] Portal da Transparência integration test - [ ] Chat flow test - [ ] Export formats test - Entregável: 10+ E2E tests - Tempo estimado: 16 horas - Arquivo: tests/e2e/

16. Security Audit - Tarefa: - [ ] Run Bandit security scanner - [ ] OWASP dependency check - [ ] Penetration testing (OWASP ZAP) - [ ] Fix critical vulnerabilities - [ ] Update security documentation - Entregável: Security report sem issues críticos - Tempo estimado: 12 horas

Milestone Semana 4: 🎯 Quality Assured - ✅ 90%+ test coverage - ✅ Performance benchmarks - ✅ E2E tests completos - ✅ Security audit passed

🎯 NOVEMBRO 2025 (4 SEMANAS)¶

Foco: Polimento, documentação e preparação para v1.0 launch

SEMANA 5 (11-17 NOV) - "Documentation Week"¶

Objetivo: Documentação completa e profissional

🔥 Prioridade CRÍTICA¶

17. Documentação Completa dos 18 Agentes - Tarefa: - [ ] Atualizar docs/agents/.md (18 arquivos) - [ ] Adicionar exemplos de uso para cada agente - [ ] Documentar parâmetros e thresholds - [ ] Adicionar diagramas de fluxo (Mermaid) - [ ] Screenshots de resultados - **Entregável*: 18 docs completos - Tempo estimado: 20 horas - Pasta: docs/agents/

18. API Documentation Enhancement - Tarefa: - [ ] OpenAPI spec completo (298 endpoints) - [ ] Request/response examples para cada endpoint - [ ] Error codes documentation - [ ] Authentication guide - [ ] Rate limiting guide - [ ] Postman collection export - Entregável: Swagger UI 100% documentado - Tempo estimado: 16 horas

📈 Prioridade ALTA¶

19. User Guides & Tutorials - Tarefa: - [ ] Quickstart guide (5 min setup) - [ ] Tutorial: Primeira investigação - [ ] Tutorial: Chat com agentes - [ ] Tutorial: Exportar relatórios - [ ] Tutorial: Deploy próprio (Railway/HF) - [ ] Video tutorials (opcional) - Entregável: 5 tutorials completos - Tempo estimado: 16 horas - Pasta: docs/tutorials/

20. Architecture Documentation - Tarefa: - [ ] Atualizar multi-agent-architecture.md - [ ] Adicionar novos diagramas Mermaid - [ ] Database schema documentation - [ ] API flow diagrams - [ ] Deployment architecture - Entregável: 10+ diagramas - Tempo estimado: 12 horas

Milestone Semana 5: 🎯 Documentation Complete - ✅ 18 agent docs - ✅ API 100% documentado - ✅ 5 tutorials - ✅ 10+ diagramas

SEMANA 6 (18-24 NOV) - "Optimization Week"¶

Objetivo: Performance e otimizações finais

🔥 Prioridade CRÍTICA¶

21. Database Query Optimization - Tarefa: - [ ] Identificar N+1 queries - [ ] Criar índices otimizados - [ ] Implement query result caching - [ ] Optimize JOIN operations - [ ] Pagination para queries grandes - Entregável: Queries <50ms (p95) - Tempo estimado: 12 horas

22. API Response Optimization - Tarefa: - [ ] Implement response compression (>80% reduction) - [ ] Optimize serialization (orjson vs json) - [ ] Add ETag caching - [ ] Implement GraphQL for complex queries - [ ] CDN setup para static assets - Entregável: Response time <100ms (p95) - Tempo estimado: 12 horas

📈 Prioridade ALTA¶

23. Agent Performance Tuning - Tarefa: - [ ] Parallel processing para agentes independentes - [ ] Optimize Zumbi FFT calculations - [ ] Cache intermediate results - [ ] Async optimization - [ ] Connection pooling tuning - Entregável: Agent processing <3s (avg) - Tempo estimado: 16 horas

24. Memory & Resource Optimization - Tarefa: - [ ] Profile memory usage - [ ] Fix memory leaks (se houver) - [ ] Optimize pandas operations - [ ] Reduce Docker image size - [ ] Configure autoscaling - Entregável: Memory usage <512MB - Tempo estimado: 12 horas

Milestone Semana 6: 🎯 Performance Optimized - ✅ Response time <100ms - ✅ Agent processing <3s - ✅ Memory usage <512MB - ✅ 99.9% uptime

SEMANA 7 (25 NOV - 01 DEZ) - "Polish & Launch Prep"¶

Objetivo: Polimento final e preparação para v1.0

🔥 Prioridade CRÍTICA¶

25. Production Deployment (Railway) - Tarefa: - [ ] Setup Railway production environment - [ ] Configure PostgreSQL + Redis - [ ] Setup Celery workers - [ ] Configure monitoring (Prometheus/Grafana) - [ ] Setup backup strategy - [ ] Configure SSL/TLS - [ ] Domain setup (api.cidadao.ai) - Entregável: Production environment live - Tempo estimado: 16 horas

26. Monitoring & Alerting Setup - Tarefa: - [ ] Configure Grafana dashboards (5+) - [ ] Setup PagerDuty/Slack alerts - [ ] Configure error tracking (Sentry) - [ ] Setup uptime monitoring (UptimeRobot) - [ ] Log aggregation (Better Stack) - Entregável: Full observability - Tempo estimado: 12 horas

📈 Prioridade ALTA¶

27. User Feedback & Beta Testing - Tarefa: - [ ] Recruit 10 beta testers - [ ] Create feedback form - [ ] Fix critical bugs reported - [ ] Implement top 3 feature requests - [ ] User satisfaction survey - Entregável: Beta feedback incorporated - Tempo estimado: 16 horas

28. Final QA & Bug Fixes - Tarefa: - [ ] Complete regression testing - [ ] Fix all P0/P1 bugs - [ ] Smoke testing em produção - [ ] Browser compatibility testing - [ ] Mobile responsiveness check - Entregável: Zero P0/P1 bugs - Tempo estimado: 20 horas

Milestone Semana 7: 🎯 Production Ready - ✅ Railway production live - ✅ Monitoring completo - ✅ Beta feedback incorporated - ✅ Zero bugs críticos

SEMANA 8 (02-08 DEZ) - "Launch Week 🚀"¶

Objetivo: Launch oficial v1.0

🎉 Launch Activities¶

29. v1.0 Release - Tarefa: - [ ] Create GitHub release v1.0.0 - [ ] Update all version numbers - [ ] Create CHANGELOG.md - [ ] Tag Docker images - [ ] Deploy to production - [ ] Announcement blog post - [ ] Social media posts - [ ] Submit to Product Hunt - Entregável: v1.0 live - Data: 30 de novembro de 2025

30. Marketing & Outreach - Tarefa: - [ ] Press release - [ ] Demo video - [ ] Landing page update - [ ] Email announcement to users - [ ] Tech blog articles - [ ] Submit to Hacker News - Entregável: 1000+ users aware

31. Post-Launch Monitoring - Tarefa: - [ ] 24/7 monitoring first 48h - [ ] Hotfix any critical issues - [ ] Collect user feedback - [ ] Performance monitoring - [ ] Support ticket response - Entregável: Smooth launch

📊 MÉTRICAS DE SUCESSO v1.0¶

Funcionalidade¶

✅ 18/18 agentes operacionais (100%)
✅ Todos com dados reais (não simulados)
✅ 2-3 ML models treinados
✅ 298 endpoints funcionais
✅ 90%+ test coverage

Performance¶

✅ API response time <100ms (p95)
✅ Agent processing <3s (avg)
✅ Uptime >99.9%
✅ Memory usage <512MB
✅ Cache hit rate >70%

Qualidade¶

✅ Zero bugs críticos
✅ Security audit passed
✅ LGPD/GDPR compliant (90%+)
✅ Documentação completa
✅ CI/CD operacional

Dados¶

✅ Portal da Transparência >50% acessível
✅ 6 TCE APIs integradas
✅ 5 CKAN portals
✅ 3 Federal APIs (IBGE, DataSUS, INEP)
✅ Database persistente

🚨 RISCOS E MITIGAÇÕES¶

RISCO 1: Portal da Transparência não liberar API key¶

Probabilidade: Alta (70%) Impacto: Médio Mitigação: - Expandir uso de TCE APIs (já temos 6) - Implementar mais CKAN portals (já temos 5) - Crawler autorizado como fallback - Parcerias com órgãos estaduais

RISCO 2: APIs Federais instáveis/lentas¶

Probabilidade: Média (50%) Impacto: Médio Mitigação: - Circuit breakers implementados - Cache agressivo (24h TTL) - Fallback para dados locais - Retry logic com backoff

RISCO 3: ML models com baixa accuracy¶

Probabilidade: Média (40%) Impacto: Alto Mitigação: - Manter thresholds estatísticos como fallback - Ensemble de múltiplos modelos - Continuous training - Feature engineering cuidadoso

RISCO 4: Performance issues em produção¶

Probabilidade: Baixa (30%) Impacto: Alto Mitigação: - Load testing antes do launch - Auto-scaling configurado - Cache multi-layer - Database optimization

RISCO 5: Atraso no cronograma¶

Probabilidade: Média (50%) Impacto: Médio Mitigação: - Buffer de 1 semana (primeira semana de dezembro) - Priorização clara (P0, P1, P2) - Scope flexibility (features nice-to-have podem ficar para v1.1) - Daily standup para tracking

📅 CRONOGRAMA VISUAL¶

OUTUBRO 2025
════════════════════════════════════════════════════════════
Semana 1 (14-20): Data Liberation      [████████████████] 100%
Semana 2 (21-27): Infrastructure       [████████████████] 100%
Semana 3 (28-03): ML Training          [████████████████] 100%
Semana 4 (04-10): Testing & Quality    [████████████████] 100%

NOVEMBRO 2025
════════════════════════════════════════════════════════════
Semana 5 (11-17): Documentation        [████████████████] 100%
Semana 6 (18-24): Optimization         [████████████████] 100%
Semana 7 (25-01): Polish & Launch Prep [████████████████] 100%
Semana 8 (02-08): Launch Week 🚀       [████████████████] 100%

MILESTONE: v1.0 LAUNCH - 30 NOV 2025

🎯 DEFINIÇÃO DE PRONTO (v1.0)¶

Must Have (Obrigatório)¶

Should Have (Desejável)¶

Could Have (Nice to Have)¶

👥 RECURSOS NECESSÁRIOS¶

Time Necessário¶

Backend Developer: 1 full-time (você)
DevOps Support: Part-time (setup CI/CD, Railway)
QA/Tester: Part-time (semanas 4, 7, 8)
Technical Writer: Part-time (semana 5)

Infraestrutura¶

Supabase: Free tier → Pro ($25/mês)
Redis Cloud: Free tier → Standard ($10/mês)
Railway: Hobby ($5/mês) → Developer ($20/mês)
HuggingFace Spaces: Free (mantém para demo)
Monitoring: Grafana Cloud free tier

Custo Estimado (Novembro/Dezembro)¶

Infraestrutura: ~$60/mês
APIs: Grátis (portais públicos)
Domínio: ~$15/ano
SSL: Grátis (Let's Encrypt)
Total: ~$75/mês

📝 CHECKLIST v1.0 FINAL¶

Funcionalidade¶

Todos os 31 tasks do roadmap completos
18/18 agentes testados em produção
Portal + TCE + CKAN funcionando
Dandara com dados reais
2+ ML models deployados
Chat consolidado
Exports funcionando (PDF, Excel, etc.)

Infraestrutura¶

Qualidade¶

Documentação¶

Launch¶

🎊 PÓS-LAUNCH (Dezembro 2025)¶

Semana 1-2 Pós-Launch¶

Monitoring intensivo
Hotfixes prioritários
User feedback collection
Performance tuning baseado em uso real

v1.1 Planning (Janeiro 2026)¶

Frontend web app (Next.js)
Mobile app (React Native)
Advanced analytics dashboard
API v2 with breaking changes
WebSocket real-time completo
Multi-tenant support

📞 COMUNICAÇÃO E TRACKING¶

Daily Standup (Sugestão)¶

O que fiz ontem?
O que vou fazer hoje?
Algum bloqueio?

Weekly Review (Sexta)¶

Milestone da semana atingido?
Riscos identificados?
Ajustes no roadmap?

Tools¶

Task Tracking: GitHub Projects ou Linear
Documentation: Notion ou Confluence
Communication: Slack ou Discord
Code Review: GitHub Pull Requests
Monitoring: Grafana + PagerDuty

🎯 CONCLUSÃO¶

Este roadmap é ambicioso mas factível com foco e disciplina. As 8 semanas estão bem distribuídas:

Outubro: Resolver problemas técnicos críticos
Novembro: Polimento e preparação para produção

Flexibilidade: Se surgir algum imprevisto, temos 1 semana de buffer (primeira semana de dezembro) antes do deadline de 30 de novembro.

Priorização: Todos os tasks marcados como 🔥 CRÍTICA são obrigatórios para v1.0. Os marcados como 📈 ALTA são desejáveis mas podem ser movidos para v1.1 se necessário.

Sucesso: Com este roadmap, você terá um sistema production-ready, profissional e completo até o final de novembro! 🚀

Criado por: Claude Code (Strategic Planning Tool) Data: 14 de outubro de 2025 Versão: 1.0 Status: Aprovado para execução

🏛️ Cidadão.AI v1.0 - Democratizando a Transparência Pública através de IA