5.9 KiB
| name | description | argument-hint |
|---|---|---|
| archon-onboarding | Onboard new developers to the Archon codebase with a comprehensive overview and first contribution guidance. Usage: /archon-onboarding | none |
You are helping a new developer get up and running with the Archon V2 Alpha project! Your goal is to provide them with a personalized onboarding experience.
What is Archon?
Archon is a centralized knowledge base for AI coding assistants. It enables Claude Code, Cursor, Windsurf, and other AI tools to access your documentation, perform smart searches, and manage tasks - all through a unified interface.
Its powered by a Model Context Protocol (MCP) server
And you can crawl and store knowledge that you can use multiple rag strategies to improve your AI coders performance.
Quick Architecture Overview
This is a true microservices architecture with 4 independent services:
- Frontend (port 3737) - React UI for managing knowledge and projects
- Server (port 8181) - Core API handling all business logic
- MCP Server (port 8051) - Lightweight MCP protocol interface
- Agents (port 8052) - AI operations with PydanticAI
All services communicate via HTTP only - no shared code, true separation of concerns.
Getting Started - Your First 30 Minutes
Prerequisites Check
You'll need:
- Docker Desktop (running)
- Supabase account (free tier works)
- OpenAI API key (or Gemini/Ollama)
- Git and basic command line knowledge
Setup
First, read the README.md file to understand the setup process, then guide the user through these steps:
- Clone the repository and set up environment variables
- Configure Supabase database with migration scripts
- Start Docker services
- Configure API keys in the UI
- Verify everything is working by testing a simple crawl
Understanding the Codebase
Decision Time
Ask the user to choose their focus area. Present these options clearly and wait for their response:
"Which area of the Archon codebase would you like to explore first?"
- Frontend (React/TypeScript) - If you enjoy UI/UX work
- Backend API (Python/FastAPI) - If you like building robust APIs
- MCP Tools (Python) - If you're interested in AI tool protocols
- RAG/Search (Python) - If you enjoy search and ML engineering
- Web Crawling (Python) - If you like data extraction challenges
Your Onboarding Analysis
Based on the user's choice, perform a deep analysis of that area following the instructions below for their specific choice. Then provide them with a structured report.
Report Structure
Your report to the user should include:
- Area Overview: Architecture explanation and how it connects to other services
- Key Files Walkthrough: Purpose of main files and their relationships
- Suggested First Contribution: A specific, small improvement with exact location
- Implementation Guide: Step-by-step instructions to make the change
- Testing Instructions: How to verify their change works correctly
If the user chose Frontend:
- Start with
archon-ui-main/src/pages/KnowledgeBasePage.tsx - Look at how it uses
services/knowledgeBaseService.ts - Take a deep dive into the frontend architecture and UI components
- Identify a potential issue that the user can easily fix and suggest a solution
- Give the user a overview of the frontend and architecture following the report format above
If the user chose Backend API:
- Start with
python/src/server/api_routes/knowledge_api.py - See how it calls
services/knowledge/knowledge_item_service.py - Take a deep dive into the FastAPI service architecture and patterns
- Identify a potential API improvement that the user can implement
- Give the user an overview of the backend architecture and suggest a contribution
If the user chose MCP Tools:
- Start with
python/src/mcp/mcp_server.py - Look at
modules/rag_module.pyfor tool patterns - Take a deep dive into the MCP protocol implementation and available tools
- Identify a missing tool or enhancement that would be valuable
- Give the user an overview of the MCP architecture and how to add new tools
If the user chose RAG/Search:
- Start with
python/src/server/services/search/vector_search_service.py - Understand the hybrid search approach
- Take a deep dive into the RAG pipeline and search strategies
- Identify a search improvement or ranking enhancement opportunity
- Give the user an overview of the RAG system and suggest optimizations
If the user chose Web Crawling:
- Start with
python/src/server/services/rag/crawling_service.py - Look at sitemap detection and parsing logic
- Take a deep dive into the crawling architecture and content extraction
- Identify a crawling enhancement or new content type support to add
- Give the user an overview of the crawling system and parsing strategies
How to Find Contribution Opportunities
When analyzing the user's chosen area, look for:
- TODO or FIXME comments in the code
- Missing error handling or validation
- UI components that could be more user-friendly
- API endpoints missing useful filters or data
- Areas with minimal or no test coverage
- Hardcoded values that should be configurable
What to Include in Your Report
After analyzing their chosen area, provide the user with:
-
Key development patterns they should know:
- Alpha mindset (break things to improve them)
- Error philosophy (fail fast with detailed errors)
- Service boundaries (no cross-service imports)
- Real-time updates via Socket.IO
- Testing approach for their chosen area
-
Specific contribution suggestion with:
- Exact file and line numbers to modify
- Current behavior vs improved behavior
- Step-by-step implementation guide
- Testing instructions
-
Common gotchas for their area:
- Service-specific pitfalls
- Testing requirements
- Local vs Docker differences
Remember to encourage the user to start small and iterate. This is alpha software designed for rapid experimentation.