Skip to content

Commit 078d680

Browse files
garland3garland3
committed
added claude.md
1 parent 3e531cf commit 078d680

File tree

3 files changed

+6354
-6067
lines changed

3 files changed

+6354
-6067
lines changed

‎.devcontainer/devcontainer.json‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,10 @@
1-
{"image":"mcr.microsoft.com/devcontainers/universal:2"}
1+
{
2+
"image": "mcr.microsoft.com/devcontainers/universal:2",
3+
"customizations": {
4+
"vscode": {
5+
"extensions": [
6+
"github.vscode-github-actions"
7+
]
8+
}
9+
}
10+
}

‎CLAUDE.md‎

Lines changed: 278 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,278 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
Atlas UI 3 is a full-stack LLM chat interface with Model Context Protocol (MCP) integration, supporting multiple LLM providers (OpenAI, Anthropic Claude, Google Gemini), RAG, and agentic capabilities.
8+
9+
**Tech Stack:**
10+
- Backend: FastAPI + WebSockets, LiteLLM, FastMCP
11+
- Frontend: React 19 + Vite 7 + Tailwind CSS
12+
- Python Package Manager: **uv** (NOT pip!)
13+
- Configuration: Pydantic with YAML/JSON configs
14+
15+
## Critical Setup Requirements
16+
17+
### Python Package Manager
18+
**ALWAYS use `uv`**, never pip or conda:
19+
```bash
20+
# Install uv first
21+
curl -LsSf https://astral.sh/uv/install.sh | sh
22+
23+
# Create venv and install dependencies
24+
uv venv
25+
source .venv/bin/activate
26+
uv pip install -r requirements.txt
27+
```
28+
29+
### Environment Setup
30+
```bash
31+
# Copy and configure environment
32+
cp .env.example .env
33+
# Set DEBUG_MODE=true for development
34+
35+
# Create required directories
36+
mkdir -p logs
37+
```
38+
39+
## Development Commands
40+
41+
### Quick Start (Recommended)
42+
```bash
43+
bash agent_start.sh
44+
```
45+
This script handles: killing old processes, clearing logs, building frontend, starting mock S3, and starting backend.
46+
47+
**Options:**
48+
- `bash agent_start.sh -f` - Only rebuild frontend
49+
- `bash agent_start.sh -b` - Only restart backend
50+
51+
### Manual Development Workflow
52+
53+
**Frontend Build (CRITICAL):**
54+
```bash
55+
cd frontend
56+
npm install
57+
npm run build # Use build, NOT npm run dev (WebSocket issues)
58+
```
59+
60+
**Backend Start:**
61+
```bash
62+
cd backend
63+
python main.py # NEVER use uvicorn --reload (causes problems)
64+
```
65+
66+
**Mock S3 (Optional):**
67+
```bash
68+
cd mocks/s3-mock
69+
python main.py # Runs on http://127.0.0.1:8003
70+
```
71+
72+
### Testing
73+
74+
**Run all tests:**
75+
```bash
76+
./test/run_tests.sh all # Takes ~2 minutes, NEVER CANCEL
77+
```
78+
79+
**Individual test suites:**
80+
```bash
81+
./test/run_tests.sh backend # ~5 seconds
82+
./test/run_tests.sh frontend # ~6 seconds
83+
./test/run_tests.sh e2e # ~70 seconds (may fail without auth config)
84+
```
85+
86+
**Frontend unit tests:**
87+
```bash
88+
cd frontend
89+
npm test # Run with Vitest
90+
npm run test:ui # Interactive UI
91+
```
92+
93+
### Linting
94+
95+
**Python:**
96+
```bash
97+
source .venv/bin/activate
98+
uv pip install ruff
99+
ruff check backend/ # ~1 second
100+
```
101+
102+
**Frontend:**
103+
```bash
104+
cd frontend
105+
npm run lint # ~1 second
106+
```
107+
108+
### Docker
109+
110+
**Build and run:**
111+
```bash
112+
docker build -t atlas-ui-3 .
113+
docker run -p 8000:8000 atlas-ui-3
114+
```
115+
116+
**Container uses Fedora latest** (note: GitHub Actions use Ubuntu runners).
117+
118+
## Architecture Overview
119+
120+
### Backend: Clean Architecture Pattern
121+
122+
```
123+
backend/
124+
├── application/ # Use cases and business logic orchestration
125+
│ └── chat/
126+
│ ├── service.py # ChatService - main orchestrator
127+
│ ├── agent/ # ReAct and Think-Act agent loops
128+
│ └── utilities/ # Helper functions
129+
├── domain/ # Pure business logic (framework-agnostic)
130+
│ ├── messages/ # Message and conversation models
131+
│ └── sessions/ # Session models
132+
├── infrastructure/ # Framework/external dependencies
133+
│ ├── app_factory.py # Dependency injection container
134+
│ └── transport/ # WebSocket adapter
135+
├── interfaces/ # Protocol definitions (abstractions)
136+
│ ├── llm.py # LLMProtocol
137+
│ ├── tools.py # ToolManagerProtocol
138+
│ └── transport.py # ChatConnectionProtocol
139+
├── modules/ # Technical implementations
140+
│ ├── llm/ # LiteLLM integration
141+
│ ├── mcp_tools/ # MCP client and tool manager
142+
│ ├── rag/ # RAG client
143+
│ ├── file_storage/ # S3 storage
144+
│ └── prompts/ # Prompt provider
145+
├── core/ # Cross-cutting concerns
146+
│ ├── middleware.py # Auth, logging
147+
│ ├── auth.py # Authorization
148+
│ └── otel_config.py # OpenTelemetry
149+
├── routes/ # HTTP endpoints
150+
└── main.py # FastAPI app + WebSocket endpoint
151+
```
152+
153+
**Key Architectural Patterns:**
154+
155+
1. **Protocol-Based Dependency Injection**: Uses Python `Protocol` (structural subtyping) instead of ABC inheritance for loose coupling
156+
157+
2. **Agent Loop Strategy Pattern**: Two implementations selectable via `APP_AGENT_LOOP_STRATEGY`:
158+
- `ReActAgentLoop`: Reasoning-Act (faster, better for tools)
159+
- `ThinkActAgentLoop`: Extended thinking (slower, complex reasoning)
160+
161+
3. **MCP Transport Auto-Detection**: Automatically detects stdio, HTTP, or SSE based on config
162+
163+
4. **Configuration Layering**:
164+
- Code defaults (Pydantic models)
165+
- `config/defaults/` (versioned)
166+
- `config/overrides/` (not in repo)
167+
- Environment variables (highest priority)
168+
169+
### Frontend: Context-Based State Management
170+
171+
```
172+
frontend/src/
173+
├── contexts/ # React Context API (no Redux)
174+
│ ├── ChatContext # Chat state (messages, selections, canvas)
175+
│ ├── WSContext # WebSocket lifecycle
176+
│ └── MarketplaceContext # MCP server discovery
177+
├── components/ # UI components
178+
├── hooks/ # Custom hooks (useMessages, useSelections, etc.)
179+
└── handlers/ # WebSocket message handlers
180+
```
181+
182+
**Event Flow:**
183+
```
184+
User Input → ChatContext → WebSocket → Backend ChatService
185+
← Streaming Updates ← tool_use/canvas_content/files_update ←
186+
```
187+
188+
## Important Development Notes
189+
190+
### Critical Restrictions
191+
- **NEVER use `uvicorn --reload`** - causes development issues
192+
- **NEVER use `npm run dev`** - has WebSocket connection problems
193+
- **ALWAYS use `npm run build`** for frontend development
194+
- **NEVER use pip** - this project requires `uv`
195+
- **NEVER CANCEL builds or tests** - they may take time but must complete
196+
- **File limit: 400 lines max** per file for maintainability
197+
198+
### Configuration Files
199+
- **LLM Config**: `config/defaults/llmconfig.yml` and `config/overrides/llmconfig.yml`
200+
- **MCP Servers**: `config/defaults/mcp.json` and `config/overrides/mcp.json`
201+
- **Environment**: `.env` (copy from `.env.example`)
202+
203+
### WebSocket Communication
204+
Backend serves WebSocket at `/ws` with message types:
205+
- `chat` - User sends message
206+
- `download_file` - Request file from S3
207+
- `reset_session` - Clear conversation history
208+
209+
Backend streams responses:
210+
- `token_stream` - Text chunks
211+
- `tool_use` - Tool execution events
212+
- `canvas_content` - HTML/markdown for canvas
213+
- `intermediate_update` - Files, images, etc.
214+
215+
### MCP Integration
216+
MCP servers defined in `config/defaults/mcp.json`. The backend:
217+
1. Auto-detects transport type (stdio/HTTP/SSE)
218+
2. Connects on startup via `MCPToolManager`
219+
3. Exposes tools to LLM via `ToolManagerProtocol`
220+
4. Supports group-based access control
221+
222+
### Agent Modes
223+
Two agent loop strategies implement different reasoning patterns:
224+
- **ReAct** (`backend/application/chat/agent/react_agent_loop.py`): Fast iteration, good for tool-heavy tasks
225+
- **Think-Act** (`backend/application/chat/agent/think_act_agent_loop.py`): Deep reasoning, slower but more thoughtful
226+
227+
### File Storage
228+
S3-compatible storage via `backend/modules/file_storage/s3_client.py`:
229+
- Production: Real S3 or S3-compatible service
230+
- Development: Mock S3 (`mocks/s3-mock/`)
231+
232+
### Security Middleware Stack
233+
```
234+
Request → SecurityHeaders → RateLimit → Auth → Route
235+
```
236+
- Rate limiting before auth to prevent abuse
237+
- Prompt injection risk detection in `backend/core/prompt_risk.py`
238+
- Group-based MCP server access control
239+
240+
### Testing Expectations
241+
- Backend tests: ~5 seconds
242+
- Frontend tests: ~6 seconds
243+
- E2E tests: ~70 seconds (may fail without auth)
244+
- Full suite: ~2 minutes
245+
- Always set adequate timeouts (120-180 seconds for full suite)
246+
247+
### Common Issues
248+
249+
1. **"uv not found"**: Install uv package manager (most common)
250+
2. **WebSocket fails**: Use `npm run build` instead of `npm run dev`
251+
3. **Backend won't start**: Check `.env` exists and `APP_LOG_DIR` is valid
252+
4. **Frontend not loading**: Verify `npm run build` completed
253+
5. **Container build SSL errors**: Use local development instead
254+
255+
## Validation Workflow
256+
257+
Before committing:
258+
1. **Build**: Frontend and backend build successfully
259+
2. **Test**: `./test/run_tests.sh all`
260+
3. **Lint**: Both Python (`ruff check backend/`) and frontend (`npm run lint`)
261+
4. **Manual**: Test in browser at http://localhost:8000
262+
5. **Exercise**: Test specific modified functionality
263+
264+
## Key File References
265+
266+
When referencing code locations, use `file_path:line_number` format for easy navigation.
267+
268+
**Core Entry Points:**
269+
- Backend: `backend/main.py` - FastAPI app + WebSocket
270+
- Frontend: `frontend/src/main.jsx` - React app entry
271+
- Chat Service: `backend/application/chat/service.py:ChatService`
272+
- Config Management: `backend/modules/config/config_manager.py`
273+
- MCP Integration: `backend/modules/mcp_tools/mcp_tool_manager.py`
274+
275+
**Protocol Definitions:**
276+
- `backend/interfaces/llm.py:LLMProtocol`
277+
- `backend/interfaces/tools.py:ToolManagerProtocol`
278+
- `backend/interfaces/transport.py:ChatConnectionProtocol`

0 commit comments

Comments
 (0)