EuConquisto Composer MCP

---
inclusion: always
---

# EuConquisto Multi-Agent System - Project Context

## Project Overview
This is an educational content management system for Brazilian schools that uses multiple AI agents to transform educational content ideas into fully formatted EuConquisto Composer content.

## Educational Context

### Target Audience
- **Ensino Fundamental**: 1º-9º anos (Elementary/Middle School: Grades 1-9)
- **Ensino Médio**: 1º-3º anos (High School: Grades 10-12)
- **Language**: Portuguese (Brazilian)
- **Educational Standards**: BNCC (Base Nacional Comum Curricular) compliance is mandatory

### BNCC Compliance Requirements
- All educational content must align with BNCC competencies and skills
- Include specific BNCC codes (e.g., "EF07CI05") in content references
- Integrate cognitive skills: Argumentar, Investigar, Comunicar, etc.
- Ensure grade-level appropriate content progression
- Validate learning objectives against BNCC standards

### Content Quality Standards
- Educational value preservation throughout all transformations
- Pedagogically sound content structure and flow
- Age-appropriate language and complexity
- Interactive elements that enhance learning
- Cultural relevance to Brazilian educational context

## Technical Architecture

### Multi-Agent System
- **Educator Agent**: Creates rich educational content with BNCC alignment
- **Content Analyst Agent**: Analyzes educational structure and learning flow
- **Widget Mapper Agent**: Maps content to interactive EuConquisto widgets
- **Format Agent**: Transforms content to Composer API format
- **QA Agent**: Validates educational and technical quality
- **Deployment Agent**: Handles API integration and browser automation

### LLM Provider Strategy
- **Primary**: Claude Max (Kiro IDE integration)
- **Fallback**: OpenAI, Gemini, Anthropic API
- **Selection**: Intelligent routing based on task requirements, cost, and quality
- **Optimization**: Support for quality, cost, speed, and performance strategies

## Version Control Standards

### Commit Message Format
Use conventional commits format:
```
type(scope): description

feat(agents): implement Educator Agent with BNCC compliance
fix(orchestration): resolve provider fallback issue
docs(api): update widget mapping documentation
test(integration): add end-to-end workflow tests
```

### Component Versioning
- All components must include version information
- Use semantic versioning (MAJOR.MINOR.PATCH)
- Update version files when making changes:
  - `src/version-info.ts` - Application version
  - Component-specific version files in each module
- Run `npm run build` to update version information

### Documentation Updates
- Update README files when adding new features
- Maintain API documentation for all public interfaces
- Include BNCC references in educational content documentation
- Update technical specifications for architectural changes

### Code Quality Standards
- TypeScript strict mode enabled
- All functions must have JSDoc comments with parameter and return types
- Use Zod for input validation and schema definitions
- Implement proper error handling with typed exceptions
- Include unit tests for all new functionality
- Maintain test coverage above 80%

## Development Guidelines

### File Organization
- Follow established directory structure: `src/{agents,providers,orchestration,config,utils,types}`
- Place tests adjacent to source files or in dedicated test directories
- Use descriptive file names that reflect component purpose
- Group related functionality in modules with index.ts exports

### Code Style
- Use camelCase for variables and functions
- Use PascalCase for classes and interfaces
- Use UPPER_SNAKE_CASE for constants
- Prefer explicit types over `any`
- Use async/await over Promise chains
- Implement proper logging with structured data

### Error Handling
- Use typed error classes for different error categories
- Implement retry logic with exponential backoff for external API calls
- Provide meaningful error messages for debugging
- Log errors with appropriate context and severity levels
- Implement graceful degradation for non-critical failures

### Testing Strategy
- Write unit tests for individual components
- Create integration tests for component interactions
- Implement end-to-end tests for complete workflows
- Use mocks for external dependencies
- Test error conditions and edge cases
- Validate BNCC compliance in educational content tests

## External Integrations

### EuConquisto Composer API
- RESTful API for content management
- JSON-based content format with widget specifications
- Authentication required for content deployment
- Support for various widget types (text, quiz, interactive, etc.)

### Widget Types Available
- Content: head-1, text-1, image-1, video-1, audio-1, list-1, table-1
- Interactive: quiz-1/2/3, drag-drop-1, hotspot-1, timeline-1, accordion-1
- Educational: activity-1, exercise-1, experiment-1, case-study-1, glossary-1
- Assessment: assessment-1, rubric-1, checklist-1, reflection-1
- Navigation: navigation-1, breadcrumb-1, index-1, search-1

### Browser Automation
- Use Playwright for automated content deployment
- Handle authentication and navigation flows
- Validate successful content publication
- Capture screenshots for verification

## Performance Considerations

### LLM Usage Optimization
- Cache responses when appropriate to reduce API calls
- Implement request batching for bulk operations
- Use provider-specific optimizations (token limits, rate limits)
- Monitor costs and usage patterns
- Implement circuit breakers for failing providers

### Memory Management
- Clean up resources after agent processing
- Implement garbage collection for large content transformations
- Monitor memory usage during parallel processing
- Use streaming for large file operations

### Scalability
- Support concurrent workflow execution
- Implement resource pooling for external connections
- Use async processing for non-blocking operations
- Design for horizontal scaling when needed

## Security Guidelines

### API Key Management
- Store API keys securely in environment variables
- Implement key rotation mechanisms
- Never commit API keys to version control
- Use different keys for development and production

### Input Validation
- Validate all user inputs with Zod schemas
- Sanitize content to prevent injection attacks
- Implement rate limiting for API endpoints
- Log security-relevant events for monitoring

### Data Privacy
- Handle educational content with appropriate privacy measures
- Implement data retention policies
- Ensure LGPD (Brazilian data protection law) compliance
- Audit data access and processing activities