Developer Guide

Welcome to the A²D developer documentation! This guide is for developers who want to contribute, understand the codebase, or extend A²D.

Overview

This guide covers:

• Understanding the A²D architecture
• Setting up your development environment
• Contributing code and documentation
• Testing and quality assurance
• Deployment and CI/CD

Who This Guide Is For

Quick Start for Contributors

1. Fork the repository on GitHub
2. Clone your fork:

   git clone https://github.com/your-username/mulesoft-mcp-mock-specs.git
   cd mulesoft-mcp-mock-specs
3. Install dependencies:

   npm install
4. Set up database: Follow Database Setup
5. Configure environment: Create .env.local with your credentials
6. Start development:

   npm run dev
7. Create a branch:

   git checkout -b feature/your-feature-name
8. Make changes and commit
9. Push and create pull request

Developer Documentation Sections

Core Documentation

CLI Tool → A²D CLI Tool

• Unified development interface
• Automated testing workflows
• Supabase health checks
• Git workflow automation

Architecture → Multi-Tenancy

• Serverless-first design
• Multi-tenant with RLS
• Next.js 16 App Router patterns
• Supabase integration

Database → Database Schema (coming soon)

• Complete schema documentation
• RLS policies
• Indexes and performance
• Migration patterns

API Internals (coming soon)

• MCP protocol implementation
• JSON-RPC 2.0 handling
• Serverless function patterns
• Error handling strategies

Component Architecture (coming soon)

• Server vs Client Components
• Reusable component patterns
• State management
• Form handling

Contributing

We welcome contributions! Here’s how to get started:

Types of Contributions

Contribution Guidelines

Before you start:

1. Check existing issues and PRs to avoid duplicates
2. Discuss major changes in an issue first
3. Follow the code style and conventions
4. Write clear commit messages
5. Add tests for new features

Pull Request Process:

1. Fork and create a feature branch
2. Make your changes
3. Test thoroughly (run npm run build)
4. Write clear PR description
5. Link related issues
6. Wait for review and address feedback

Code Standards

TypeScript

A²D uses TypeScript 5 in strict mode:

// ✅ Good: Explicit types
interface MCPServer {
  id: string
  name: string
  type: 'url' | 'openapi' | 'mock'
}
 
// ✅ Good: Type-safe function
function createServer(data: Partial<MCPServer>): Promise<MCPServer> {
  // Implementation
}
 
// ❌ Bad: Using any
function processData(data: any) {
  // Avoid this
}

React Components

Prefer Server Components by default:

// ✅ Server Component (default)
export default async function ServersPage() {
  const servers = await fetchServers()
  return <ServersList servers={servers} />
}
 
// ✅ Client Component when needed
'use client'
export function ServersList({ servers }: Props) {
  const [filter, setFilter] = useState('')
  // Interactive logic
}

Naming Conventions

• Files: kebab-case.tsx
• Components: PascalCase
• Functions: camelCase
• Constants: UPPER_SNAKE_CASE
• Types: PascalCase

Testing

Planned Testing Stack

• Unit Tests: Jest + React Testing Library
• Integration Tests: API route testing
• E2E Tests: Playwright
• Coverage Target: >80%

Testing Guidelines (Future)

// Example unit test structure
describe('MCPServerService', () => {
  it('should create server with valid data', async () => {
    const server = await createServer({
      name: 'Test Server',
      type: 'mock'
    })
    expect(server.name).toBe('Test Server')
  })
})

Development Workflow

Git Workflow

Branch naming:

• feature/description - New features
• fix/description - Bug fixes
• docs/description - Documentation updates
• refactor/description - Code improvements

Commit messages:

# Format: type(scope): description
feat(mcp): Add resource template support
fix(auth): Resolve signup redirect issue
docs(api): Update error handling guide

Code Review Process

1. Automated checks run on PR
2. Maintainer review (1-2 reviewers)
3. Address feedback
4. Approval and merge

Build and Deploy

Local Build

# Type check
npm run type-check
 
# Lint
npm run lint
 
# Build
npm run build
 
# Test build
npm run start

CI/CD

Automatic actions:

• Lint on PR
• Type check on PR
• Build verification
• Deploy preview on PR
• Deploy production on merge to main

Project Structure

mulesoft-mcp-mock-specs/
├── app/                    # Next.js App Router
│   ├── (app)/             # Protected routes
│   ├── (auth)/            # Auth pages
│   ├── api/               # API routes
│   └── globals.css
├── components/            # React components
│   ├── ui/               # Base UI components
│   └── ...               # Feature components
├── lib/                   # Utilities
│   ├── supabase/         # Database clients
│   ├── mcp/              # MCP utilities
│   └── design-rules/     # Validation
├── types/                 # TypeScript types
├── supabase/             # Database migrations
└── public/               # Static assets

Getting Help

Community

• GitHub Issues: ma2d-ai-issues
• GitHub Discussions: ma2d-ai-issues/discussions

Documentation

• Architecture: Multi-Tenancy
• API Reference: API Reference
• Core Concepts: Core Concepts

Code of Conduct

We are committed to providing a welcoming and inclusive environment. All contributors are expected to:

• Be respectful and considerate
• Welcome newcomers and help them learn
• Focus on what is best for the community
• Show empathy towards other community members

License

A²D is open source under the Apache 2.0 License.

• ✅ Freedom to use, modify, and distribute
• ✅ Patent protection
• ✅ Commercial use allowed
• ✅ Attribution required

See LICENSE for full details.

Roadmap

See ROADMAP.md for planned features and improvements.

Ready to contribute? Check out open issues or start a discussion!