docs/development/README.md

💻 Development Guide - Cidadão.AI Backend

Author: Anderson Henrique da Silva Last Updated: 2025-10-03 (São Paulo, Brazil)

This directory contains comprehensive developer guides and implementation references for contributing to the Cidadão.AI Backend project.

📚 Available Guides

Getting Started

• CONTRIBUTING.md - Complete contribution guide
  • Code standards and conventions
  • Git workflow and commit guidelines
  • Pull request process
  • Development environment setup

Implementation Guides

• CONVERSATIONAL_AI_IMPLEMENTATION.md - Conversational AI system

  • Portuguese intent detection
  • Multi-agent dialogue flow
  • Context management
  • Response generation

• INDEX_CHAT_IMPLEMENTATION.md - Chat implementation details

  • Real-time chat architecture
  • SSE streaming responses
  • Message handling patterns
  • Error recovery strategies

• maritaca_integration.md - Maritaca LLM integration

  • API integration patterns
  • Optimization techniques
  • Rate limiting and caching
  • Cost optimization

Technical Implementation

• CORS_CONFIGURATION.md - CORS setup and security

  • Production-ready CORS configuration
  • Security best practices
  • Vercel/HuggingFace deployment specifics

• CURSOR_PAGINATION_IMPLEMENTATION.md - Cursor-based pagination

  • Efficient pagination for large datasets
  • Performance optimizations
  • API design patterns

• GZIP_COMPRESSION_IMPLEMENTATION.md - Response compression

  • GZIP middleware configuration
  • Compression strategies
  • Performance impact analysis

• FRONTEND_INTEGRATION_GUIDE.md - Frontend integration

  • API client setup
  • Authentication flow
  • WebSocket integration
  • Error handling patterns

Code Examples

• examples/ - Working code examples
  • Integration examples
  • Agent usage patterns
  • API client implementations

🚀 Quick Start for Developers

1. Environment Setup

# Clone the repository
git clone https://github.com/anderson-ufrj/cidadao.ai-backend
cd cidadao.ai-backend

# Install dependencies
make install-dev

# Copy environment template
cp .env.example .env
# Edit .env with your configuration

2. Run Development Server

# Start backend with hot reload
make run-dev

# Or directly with Python
python -m src.api.app

3. Run Tests

# Run all tests with coverage (80% minimum required)
make test

# Run specific test categories
make test-unit        # Unit tests only
make test-agents      # Multi-agent tests
make test-integration # Integration tests

4. Code Quality Checks

# Format code
make format

# Lint code
make lint

# Type checking
make type-check

# Run all checks
make check

# Full CI locally
make ci

📋 Development Workflow

1. Before Starting

• Read CONTRIBUTING.md
• Set up pre-commit hooks (optional but recommended)
• Join our communication channels (if available)

2. During Development

• Follow code standards from CONTRIBUTING.md
• Write tests for new features (TDD approach)
• Update documentation as you code
• Run make check frequently

3. Before Committing

• Run make ci to ensure all checks pass
• Write descriptive commit messages (conventional commits)
• Update relevant documentation
• Add tests for new functionality

4. Pull Request

• Follow PR template guidelines
• Ensure CI passes
• Request review from maintainers
• Address review feedback promptly

🏗️ Architecture References

For architectural decisions and patterns:

• Architecture Overview
• Agent System Design
• Performance Optimization
• Monitoring & Observability

🤖 Agent Development

For creating or modifying agents:

• Agent Documentation
• Abaporu (Master Orchestrator)
• Zumbi (Anomaly Detection)
• Agent Status Overview

🔧 Common Development Tasks

Adding a New Agent

1. Create agent class in src/agents/
2. Register in src/agents/__init__.py
3. Add tests in tests/unit/agents/
4. Create documentation in docs/agents/
5. Update agent status document

Adding a New API Endpoint

1. Create/update router in src/api/routers/
2. Add endpoint to src/api/app.py
3. Write integration tests
4. Update API documentation
5. Add to API_ENDPOINTS_MAP.md

Performance Optimization

1. Profile the code to identify bottlenecks
2. Implement caching where appropriate
3. Use async/await for I/O operations
4. Add monitoring metrics
5. Document optimizations

📊 Testing Strategy

• Unit Tests: Test individual components in isolation
• Integration Tests: Test component interactions
• Agent Tests: Test multi-agent coordination
• Performance Tests: Benchmark critical paths
• Security Tests: Validate authentication and authorization

Target: 80% code coverage (enforced in CI)

🔒 Security Considerations

• Never commit secrets or API keys
• Use environment variables for configuration
• Follow OWASP security best practices
• Validate all user inputs
• Implement rate limiting on public endpoints
• Keep dependencies updated

🐛 Debugging Tips

# Enable debug logging for agents
import logging
logging.getLogger("src.agents").setLevel(logging.DEBUG)

# Use pdb for interactive debugging
import pdb; pdb.set_trace()

# Profile performance
from src.core.monitoring import agent_metrics
# Metrics automatically collected

📖 Additional Resources

• API Documentation
• Deployment Guide
• Troubleshooting
• Project Roadmap

🤝 Getting Help

If you encounter issues:

1. Check Troubleshooting Guide
2. Search existing GitHub issues
3. Review relevant documentation
4. Create a new issue with detailed information

---

Happy coding! 🚀

Remember: Quality over speed. Write tests, document your code, and follow best practices.