Industrial-grade deep research agent system with live architecture visualization powered by LikeC4.
- 🤖 5-Agent Intelligent Workflow: Plan → Research → Synthesize → Write → Review
- 📊 Live Architecture Visualization: LikeC4-powered C4 diagrams that update with code
- 🔄 Event Sourcing: Complete audit trail with PostgreSQL event store
- 🖥️ Desktop Application: Electron + React for native experience
- 🐳 Docker Local Sandbox: Secure isolated code execution (replaces E2B)
- 🎭 Mock Mode: Demo without API keys
- Node.js 20+
- Python 3.11+
- Docker Desktop
- npm 10+
# Clone repository
git clone <repository-url>
cd deep-research-agent-v2
# Install dependencies
npm run setup
# Start development environment
docker-compose up -d # Start PostgreSQL
npm run backend # Start FastAPI backend
npm run dev # Start Electron app
npm run likec4 # Start architecture viewerCopy .env.example to .env and configure:
# Required (PostgreSQL)
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/deepresearch
# Optional (for real LLM - defaults to Mock mode)
OPENAI_API_KEY=sk-...
TAVILY_API_KEY=tvly-...
# Application
MOCK_MODE=true # Set to false for real API calls
LOG_LEVEL=infoView live architecture diagrams at http://localhost:4040 after running npm run likec4.
- Desktop App (Electron + React): User interface
- Backend API (FastAPI): Orchestration and business logic
- LangGraph Orchestrator: 5-agent workflow state machine
- Docker Sandbox: Isolated Python code execution
- PostgreSQL: Event store + projections
- LikeC4: Architecture visualization
- Planner Agent: Breaks research query into sub-tasks
- Research Agent: Parallel web search and data extraction
- Synthesizer Agent: Consolidates findings
- Writer Agent: Generates final report with citations
- Critic Agent: Quality review and validation
deep-research-agent-v2/
├── src/
│ ├── architecture/ # LikeC4 architecture models
│ │ ├── workspace.c4 # Root workspace definition
│ │ ├── model/ # C4 model components
│ │ └── views/ # Architecture views
│ ├── backend/ # FastAPI backend
│ │ ├── agents/ # LangGraph agents
│ │ ├── api/ # REST endpoints
│ │ ├── core/ # Event sourcing
│ │ ├── services/ # Docker sandbox, etc.
│ │ └── main.py # Application entry
│ ├── desktop/ # Electron app
│ │ ├── main/ # Electron main process
│ │ └── renderer/ # React UI
│ └── shared/ # Shared types/utilities
├── docker-compose.yml # Local development stack
└── package.json # Monorepo configuration
# Backend tests
cd src/backend
pytest
# Frontend tests
npm test --workspace=src/desktop
# E2E tests
npm run test:e2e# Python
cd src/backend
black .
ruff check .
mypy .
# TypeScript
npm run lint
npm run typecheck# Backend Docker image
docker build -f docker/backend.Dockerfile -t deepresearch-backend .
# Desktop app
npm run build --workspace=src/desktopThe system uses Docker for secure, isolated code execution instead of E2B:
Security Features:
- Network disabled
- CPU/Memory limits
- Read-only filesystem (except workspace)
- Auto-cleanup after execution
- Timeout protection
Pre-installed Libraries:
- pandas
- numpy
- matplotlib
- seaborn
- scipy
Access interactive API docs at http://localhost:8000/docs after starting the backend.
POST /research- Create research taskGET /research/{id}- Get research statusGET /research/{id}/stream- SSE progress updatesGET /health- Health check
See CONTRIBUTING.md for development guidelines.
MIT License - see LICENSE for details.
- ✅ LikeC4 architecture visualization
- ✅ 5-agent workflow
- ✅ Docker sandbox
- ✅ Event sourcing
- ✅ Mock mode
- Multi-language support
- PDF export
- Custom agent plugins
- Cloud deployment
- Collaboration features
Built with: