Developer Onboarding Guide

Welcome to the AICR platform. This guide will get you up to speed on the ecosystem and prepare you to contribute.

Week 1: Environment Setup

Day 1-2: Local Development

1. Clone the monorepo

   git clone https://github.com/AICodeRally/aicr.git ~/dev/aicr
   cd ~/dev/aicr
   pnpm install

2. Set up environment variables

   cp .env.example .env.local
   # Get credentials from Vercel or team lead

3. Start the development server

   pnpm dev

4. Verify access to:

   • Main app: http://localhost:3000 (opens in a new tab)
   • Docs: http://localhost:3001 (opens in a new tab)
   • Playground: http://localhost:3002 (opens in a new tab)

Day 3-4: Database Setup

1. Neon PostgreSQL

   • Request access to Neon dashboard
   • Create a development branch from main
   • Update DATABASE_URL in .env.local

2. Run migrations

   cd apps/aicr
   pnpm prisma migrate dev
   pnpm prisma generate

3. Seed sample data

   pnpm prisma db seed

Day 5: AI Infrastructure

1. Install Ollama (optional but recommended)

   # macOS
   brew install ollama
   ollama serve
    
   # Pull models
   ollama pull nomic-embed-text
   ollama pull llama3

2. Test AI connectivity

   curl http://localhost:11434/api/tags

3. Verify OpenAI key (get from team lead)

   export OPENAI_API_KEY=sk-...
   curl https://api.openai.com/v1/models \
     -H "Authorization: Bearer $OPENAI_API_KEY"

Week 2: Codebase Exploration

Key Directories to Understand

Critical Files

1. CLAUDE.md - AI agent instructions for the repo
2. apps/aicr/prisma/schema.prisma - Database schema
3. packages/ai-router/src/client.ts - AI client implementation
4. packages/contracts/src/context.ts - Context envelope types

Documentation to Read

1. AI Gateway Overview - How AI routing works
2. Ecosystem Overview - Project inventory
3. Architecture Overview - Platform design
4. Pack System - Capability delivery model

Week 3: Knowledge Base Work

Your initial assignment is documenting and building out the knowledge base.

Task 1: Audit Existing Documentation

1. Find all CLAUDE.md files

   find ~/dev -name "CLAUDE.md" -type f 2>/dev/null

2. For each file, document:

   • Project name and purpose
   • Key directories and files
   • Dependencies on other projects
   • Environment requirements

3. Create inventory spreadsheet with columns:

   • Project Name
   • Location
   • Has CLAUDE.md (Y/N)
   • Vercel Connected (Y/N)
   • Database Type
   • AI Integration (None/Ollama/OpenAI/Both)

Task 2: Knowledge Base Content

1. Review SPM knowledge cards

   ~/dev/intelligentspm/src/data/spm-kb-cards.json
   • 929 cards covering SPM domain knowledge
   • Used by AskSPM RAG system

2. Document card structure:

   • Pillars (categories)
   • Keywords
   • Content format
   • Embedding approach

3. Identify gaps:

   • Missing topics
   • Outdated content
   • Inconsistent formatting

Task 3: Documentation Site

1. Run docs locally

   cd ~/dev/aicr/apps/docs
   pnpm dev

2. Add missing pages:

   • Project pages for each app
   • API reference for each service
   • Troubleshooting guides

3. Follow MDX conventions:

   • Use frontmatter for metadata
   • Include code examples
   • Add navigation links

Common Tasks

Running Tests

# All tests
pnpm test
 
# Specific package
pnpm --filter @aicr/ai-router test
 
# Watch mode
pnpm test -- --watch

Creating a Branch

git checkout -b feature/your-feature
# Make changes
git add .
git commit -m "feat: description"
git push -u origin feature/your-feature

Deploying to Preview

1. Push to branch (auto-deploys to Vercel preview)
2. Check preview URL in PR comments
3. Test functionality
4. Request review

Getting Help

• Slack: #dev-help channel
• GitHub: Open issue or discussion
• AI Assistant: Use Claude Code with project CLAUDE.md
• Docs: Start here, then architecture docs

Checklist

• Local environment running
• Database connected
• AI providers working (Ollama or OpenAI)
• Can access all critical apps
• Read core documentation
• First commit submitted
• Knowledge base audit started