Developer Guide
Getting Started

Getting Started

This guide will help you set up your development environment for the MTD project.

Prerequisites

Required Software

  • Node.js: v18+ (for mtd-web-v2 and mtd-docs)
  • Python: 3.9+ (for mtd-ai)
  • Git: Latest version
  • pnpm: Latest version (for mtd-docs)
  • Firebase CLI: For authentication and deployment

Recommended Tools

  • VS Code: With recommended extensions
  • Docker: For containerized development
  • Postman: For API testing

Initial Setup

1. Clone the Repository

git clone [repository-url]
cd mtd

The default branch is dev, which contains the latest development code.

2. Backend Setup (mtd-ai)

cd mtd-ai
 
# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
 
# Install dependencies
pip install -r requirements.txt
 
# Set up development environment
python setup_development.py
python setup_firebase.py
 
# Copy environment variables
cp .env.example .env
# Edit .env with your configuration

3. Frontend Setup (mtd-web-v2)

cd mtd-web-v2
 
# Install dependencies
npm install
 
# Copy environment variables
cp .env.local.example .env.local
# Edit .env.local with your configuration
 
# Run development server
npm run dev

4. Documentation Setup (mtd-docs)

cd mtd-docs
 
# Install dependencies with pnpm
pnpm install
 
# Run documentation server
pnpm dev

Environment Configuration

Backend Environment Variables (mtd-ai)

FIREBASE_CERT_PATH=./path-to-firebase-cert.json
GOOGLE_API_KEY=your-google-api-key
PROJECT_ID=your-gcp-project-id
ENABLE_VERTEX_AGENT_ENGINE=true

Frontend Environment Variables (mtd-web-v2)

NEXT_PUBLIC_FIREBASE_API_KEY=your-firebase-api-key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your-auth-domain
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your-project-id
NEXT_PUBLIC_API_URL=http://localhost:8000

Running the Full Stack

Development Mode

  1. Start Backend (Terminal 1):
cd mtd-ai
./start_dev.sh
  1. Start Frontend (Terminal 2):
cd mtd-web-v2
npm run dev
  1. Start Documentation (Terminal 3, optional):
cd mtd-docs
pnpm dev

Access Points

Development Workflow

1. Create Feature Branch

git checkout dev
git pull origin dev
git checkout -b feature/your-feature-name

2. Make Changes

  • Follow coding guidelines for each project
  • Write tests for new functionality
  • Update documentation as needed

3. Pre-commit Checks

Backend (mtd-ai):

black .
isort .
python run_tests.py

Frontend (mtd-web-v2):

npm run type-check  # Critical - runs TypeScript, ESLint, and Prettier

4. Create Pull Request

git push origin feature/your-feature-name
# Create PR to dev branch on GitHub

Common Issues

Port Conflicts

If default ports are in use:

  • Backend: Set PORT=8001 in .env
  • Frontend: Use npm run dev -- -p 3001
  • Docs: Use pnpm dev -- -p 3002

Firebase Authentication

Ensure Firebase credentials are properly configured:

  1. Download service account JSON from Firebase Console
  2. Place in secure location (not in repo)
  3. Update FIREBASE_CERT_PATH in .env

Python Dependencies

If dependency installation fails:

pip install --upgrade pip
pip install -r requirements.txt --no-cache-dir

Next Steps

  • Review Git Branching Strategy
  • Explore Architecture documentation
  • Check project-specific CLAUDE.md files for detailed patterns
  • Join development channels for team communication

Useful Commands Reference

Backend (mtd-ai)

  • ./start_dev.sh - Start development server
  • python run_tests.py - Run test suite
  • black . && isort . - Format code

Frontend (mtd-web-v2)

  • npm run dev - Start development server
  • npm run type-check - Comprehensive checks
  • npm run build - Production build

Documentation (mtd-docs)

  • pnpm dev - Start doc server
  • pnpm build - Build documentation
  • pnpm start - Serve production build
OverviewGit Branching Strategy