forked from cardosofelipe/fast-next-template
Felipe Cardoso
e5975fa5d0
Core MCP client implementation with comprehensive tooling:
**Services:**
- MCPClientManager: Main facade for all MCP operations
- MCPServerRegistry: Thread-safe singleton for server configs
- ConnectionPool: Connection pooling with auto-reconnection
- ToolRouter: Automatic tool routing with circuit breaker
- AsyncCircuitBreaker: Custom async-compatible circuit breaker
**Configuration:**
- YAML-based config with Pydantic models
- Environment variable expansion support
- Transport types: HTTP, SSE, STDIO
**API Endpoints:**
- GET /mcp/servers - List all MCP servers
- GET /mcp/servers/{name}/tools - List server tools
- GET /mcp/tools - List all tools from all servers
- GET /mcp/health - Health check all servers
- POST /mcp/call - Execute tool (admin only)
- GET /mcp/circuit-breakers - Circuit breaker status
- POST /mcp/circuit-breakers/{name}/reset - Reset circuit breaker
- POST /mcp/servers/{name}/reconnect - Force reconnection
**Testing:**
- 156 unit tests with comprehensive coverage
- Tests for all services, routes, and error handling
- Proper mocking and async test support
**Documentation:**
- MCP_CLIENT.md with usage examples
- Phase 2+ workflow documentation
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
294 lines
8.3 KiB
Markdown
294 lines
8.3 KiB
Markdown
# Development Workflow
|
|
|
|
This document defines the development workflow, branching strategy, and issue management rules for Syndarix.
|
|
|
|
## Issue-Driven Development
|
|
|
|
**Every piece of work MUST have an issue in the Gitea tracker first.**
|
|
|
|
- Issue tracker: https://gitea.pragmazest.com/cardosofelipe/syndarix/issues
|
|
- Create detailed, well-scoped issues before starting work
|
|
- Structure issues to enable parallel work by multiple agents
|
|
- Reference issues in commits and PRs
|
|
|
|
---
|
|
|
|
## Git Branching Strategy
|
|
|
|
### Branch Naming Convention
|
|
|
|
```
|
|
feature/<issue-number>-<short-description>
|
|
```
|
|
|
|
Examples:
|
|
- `feature/123-user-authentication`
|
|
- `feature/456-project-dashboard`
|
|
|
|
### Branch Workflow
|
|
|
|
```
|
|
main (production-ready)
|
|
└── dev (integration branch)
|
|
└── feature/123-description (issue branch)
|
|
```
|
|
|
|
### Rules
|
|
|
|
1. **Every issue gets its own feature branch**
|
|
2. **No direct commits to `main` or `dev`**
|
|
3. **Keep branches focused and small**
|
|
4. **Delete branches after merge**
|
|
5. **All branches must be mergeable to dev** - if work isn't ready to merge, keep it in a separate branch
|
|
|
|
---
|
|
|
|
## Issue and Branch Structure for Features
|
|
|
|
### Single Branch per Feature
|
|
|
|
For UI/UX features that require both design and implementation:
|
|
|
|
1. **Create a single feature branch** for both design prototype and implementation
|
|
2. **Do NOT create separate branches** for design vs implementation
|
|
|
|
### Issue Structure Options
|
|
|
|
Choose one of these approaches based on complexity:
|
|
|
|
#### Option A: Single Issue with Tasks (Recommended for most features)
|
|
|
|
```markdown
|
|
## Issue: Add User Profile Page (#123)
|
|
|
|
### Tasks
|
|
- [ ] Design: Create interactive prototype in /prototypes
|
|
- [ ] Design: Get user approval on the design
|
|
- [ ] Implementation: Build page following design system
|
|
- [ ] Implementation: Write tests
|
|
- [ ] Cleanup: Remove prototype after implementation
|
|
```
|
|
|
|
Branch: `feature/123-user-profile-page`
|
|
|
|
#### Option B: User Story with Sub-Issues (For complex features)
|
|
|
|
```markdown
|
|
## User Story: Project Management (#100)
|
|
├── Sub-issue: Design project dashboard (#101)
|
|
├── Sub-issue: Implement project dashboard (#102)
|
|
├── Sub-issue: Design project settings (#103)
|
|
└── Sub-issue: Implement project settings (#104)
|
|
```
|
|
|
|
Branch: `feature/100-project-management` (single branch for the entire user story)
|
|
|
|
**Important:** Even with multiple sub-issues, use a **single branch** for the user story.
|
|
|
|
---
|
|
|
|
## UI/UX Design Workflow
|
|
|
|
### For New UI Features
|
|
|
|
1. **Create Issue**: Use `design` label
|
|
2. **Build Prototype**: Create in `/frontend/src/app/[locale]/prototypes/<feature>/`
|
|
3. **User Review**: Get feedback on the prototype
|
|
4. **Approval**: User approves design before implementation
|
|
5. **Implementation**: Build in production location following design system
|
|
6. **Cleanup**: Remove prototype after implementation
|
|
|
|
### Design Guidelines
|
|
|
|
| Phase | Requirements |
|
|
|-------|-------------|
|
|
| **Prototype** | Best effort to match design system (not required) |
|
|
| **Production** | MUST follow `frontend/docs/design-system/` strictly |
|
|
|
|
---
|
|
|
|
## Testing Requirements
|
|
|
|
**All code must be tested. No exceptions.**
|
|
|
|
### Testing Approach
|
|
|
|
- **TDD preferred**: Write tests first when possible
|
|
- **Test after**: If not TDD, write tests immediately after testable code
|
|
- **Coverage types**: Unit, integration, functional, E2E as appropriate
|
|
- **Minimum coverage**: Aim for >90% on new code
|
|
|
|
### Testing Commands
|
|
|
|
```bash
|
|
# Backend
|
|
IS_TEST=True uv run pytest # Unit/integration tests
|
|
make test-e2e # E2E tests (requires Docker)
|
|
|
|
# Frontend
|
|
npm test # Unit tests
|
|
npm run test:e2e # E2E tests
|
|
```
|
|
|
|
---
|
|
|
|
## Code Review Process
|
|
|
|
**Before merging any feature branch, code must pass multi-agent review:**
|
|
|
|
| Check | Description |
|
|
|-------|-------------|
|
|
| Bug hunting | Logic errors, edge cases, race conditions |
|
|
| Linting | `ruff check` / `eslint` passes with no errors |
|
|
| Typing | `mypy` / `tsc --noEmit` passes with no errors |
|
|
| Formatting | Code follows style guidelines |
|
|
| Performance | No obvious bottlenecks or N+1 queries |
|
|
| Security | No vulnerabilities (OWASP top 10) |
|
|
| Architecture | Follows established patterns and ADRs |
|
|
|
|
**Issue is NOT done until review passes with flying colors.**
|
|
|
|
---
|
|
|
|
## QA Before Main
|
|
|
|
**Before merging `dev` into `main`:**
|
|
|
|
- [ ] Full test suite passes
|
|
- [ ] Manual QA verification
|
|
- [ ] Performance baseline check
|
|
- [ ] Security scan
|
|
- [ ] Code must be clean, functional, bug-free, well-architected, and secure
|
|
|
|
---
|
|
|
|
## Commit Message Format
|
|
|
|
```
|
|
<type>(<scope>): <description>
|
|
|
|
[optional body]
|
|
|
|
[optional footer]
|
|
```
|
|
|
|
### Types
|
|
|
|
- `feat`: New feature
|
|
- `fix`: Bug fix
|
|
- `docs`: Documentation only
|
|
- `style`: Formatting, missing semicolons, etc.
|
|
- `refactor`: Code change that neither fixes a bug nor adds a feature
|
|
- `test`: Adding missing tests
|
|
- `chore`: Maintenance tasks
|
|
|
|
### Examples
|
|
|
|
```
|
|
feat(auth): add password reset functionality
|
|
fix(api): handle null response in user endpoint
|
|
docs(readme): update installation instructions
|
|
test(frontend): add unit tests for ProjectDashboard
|
|
```
|
|
|
|
---
|
|
|
|
## Pull Request Process
|
|
|
|
1. **Create PR from feature branch to dev**
|
|
2. **PR title**: Same format as commit messages
|
|
3. **PR body**: Include summary, test plan, and issue reference
|
|
4. **Wait for CI**: All checks must pass
|
|
5. **Code review**: Address all feedback
|
|
6. **Merge**: Squash and merge when approved
|
|
7. **Cleanup**: Delete feature branch after merge
|
|
|
|
---
|
|
|
|
## Documentation Updates
|
|
|
|
- Keep `docs/architecture/IMPLEMENTATION_ROADMAP.md` updated
|
|
- Mark completed items as work progresses
|
|
- Add new items discovered during implementation
|
|
- Update ADRs when architectural decisions change
|
|
|
|
---
|
|
|
|
## Phase 2+ Implementation Workflow
|
|
|
|
**For complex infrastructure issues (Phase 2 MCP, core systems), follow this rigorous process:**
|
|
|
|
### 1. Branch Setup
|
|
```bash
|
|
# Create feature branch from dev
|
|
git checkout dev && git pull
|
|
git checkout -b feature/<issue-number>-<description>
|
|
```
|
|
|
|
### 2. Planning Phase
|
|
- Read the issue thoroughly, understand ALL sub-tasks
|
|
- Identify components and their dependencies
|
|
- Determine if multi-agent parallel execution is appropriate
|
|
- Create a detailed execution plan before writing any code
|
|
|
|
### 3. Implementation with Continuous Testing
|
|
**After EACH sub-task:**
|
|
- [ ] Run unit tests for the component
|
|
- [ ] Run integration tests if applicable
|
|
- [ ] Verify type checking passes
|
|
- [ ] Verify linting passes
|
|
- [ ] Keep coverage high (aim for >90%)
|
|
|
|
**Both modules must be tested:**
|
|
- Backend: `IS_TEST=True uv run pytest` + E2E tests
|
|
- Frontend: `npm test` + E2E tests (if applicable)
|
|
|
|
### 4. Multi-Agent Review (MANDATORY before considering done)
|
|
Before closing an issue, perform deep review from multiple angles:
|
|
|
|
| Review Type | Focus Areas |
|
|
|-------------|-------------|
|
|
| **Code Quality** | Logic errors, edge cases, race conditions, error handling |
|
|
| **Security** | OWASP Top 10, input validation, authentication, authorization |
|
|
| **Performance** | N+1 queries, memory leaks, inefficient algorithms |
|
|
| **Architecture** | Pattern adherence, separation of concerns, extensibility |
|
|
| **Testing** | Coverage completeness, test quality, edge case coverage |
|
|
| **Documentation** | Code comments, README, API docs, usage examples |
|
|
|
|
**No stone unturned. No sloppy results. No unreviewed work.**
|
|
|
|
### 5. Final Validation
|
|
- [ ] All tests pass (unit, integration, E2E)
|
|
- [ ] Type checking passes
|
|
- [ ] Linting passes
|
|
- [ ] Documentation updated
|
|
- [ ] Coverage meets threshold
|
|
- [ ] Issue checklist 100% complete
|
|
- [ ] Multi-agent review passed
|
|
|
|
### When to Use Parallel Agents
|
|
Use multiple agents working in parallel when:
|
|
- Sub-tasks are independent (no shared state/dependencies)
|
|
- Different expertise areas (backend vs frontend)
|
|
- Time-critical deliveries with clear boundaries
|
|
|
|
Do NOT use parallel agents when:
|
|
- Tasks share state or have dependencies
|
|
- Sequential testing is required
|
|
- Integration points need careful coordination
|
|
|
|
---
|
|
|
|
## Quick Reference
|
|
|
|
| Action | Command/Location |
|
|
|--------|-----------------|
|
|
| Create branch | `git checkout -b feature/<issue>-<desc>` |
|
|
| Run backend tests | `IS_TEST=True uv run pytest` |
|
|
| Run frontend tests | `npm test` |
|
|
| Check types (backend) | `uv run mypy src/` |
|
|
| Check types (frontend) | `npm run type-check` |
|
|
| Lint (backend) | `uv run ruff check src/` |
|
|
| Lint (frontend) | `npm run lint` |
|
|
| Generate API client | `npm run generate:api` |
|