160 lines
6.4 KiB
Markdown
160 lines
6.4 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
**Neural Sync** is an AI-native project management platform designed for small (10-person) AI/ML technical teams. Unlike traditional PM tools that manage static tasks, this system manages "Living Context" - external signals, AI experiments, and cognitive knowledge nodes with version tracking and semantic embedding.
|
|
|
|
### Core Philosophy
|
|
|
|
The system operates on three pillars:
|
|
1. **Signals (Pulse)**: External triggers (market news, model releases, competitor updates) captured from sources like HackerNews
|
|
2. **Context Nodes (Cognitive Core)**: Atomic knowledge units with vector embeddings for semantic search - when these change, dependent experiments auto-flag as "outdated"
|
|
3. **Experiments (Lab)**: Evaluation-driven tasks where success is measured by metrics (accuracy, latency) rather than just completion
|
|
|
|
## Technology Stack
|
|
|
|
### Backend
|
|
- **FastAPI** with async/await patterns
|
|
- **SQLAlchemy 2.0** async with database-agnostic design (PostgreSQL with pgvector or SQLite fallback)
|
|
- **Alembic** for database migrations
|
|
- **Ollama** integration for local LLM operations (llama3, nomic-embed-text models)
|
|
|
|
### Frontend
|
|
- **Vue 3** with Composition API and `<script setup>` syntax
|
|
- **Naive UI** component library (chosen over Element Plus for data-dense applications)
|
|
- **TypeScript**
|
|
- **Vite** 8.x beta
|
|
- **ECharts** via vue-echarts for radar/competitiveness visualization
|
|
|
|
## Common Development Commands
|
|
|
|
### Backend
|
|
|
|
```bash
|
|
# Navigate to backend
|
|
cd backend
|
|
|
|
# Install dependencies
|
|
pip install -r requirements.txt
|
|
|
|
# Run database migrations
|
|
alembic upgrade head
|
|
|
|
# Seed initial data (development only)
|
|
python -m seed
|
|
|
|
# Start backend server (dev mode with hot reload)
|
|
uvicorn app.main:app --reload --port 8000
|
|
```
|
|
|
|
### Frontend
|
|
|
|
```bash
|
|
# Navigate to frontend
|
|
cd frontend
|
|
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Start dev server (accessible on network with --host flag)
|
|
npm run dev -- --host
|
|
|
|
# Production build
|
|
npm run build
|
|
|
|
# Preview production build
|
|
npm run preview
|
|
```
|
|
|
|
### Database Setup
|
|
|
|
**PostgreSQL (production)**:
|
|
```bash
|
|
# Create database with pgvector extension
|
|
createdb neural_sync
|
|
psql neural_sync -c "CREATE EXTENSION vector;"
|
|
```
|
|
|
|
**SQLite (development)**:
|
|
- Set `DATABASE_URL=sqlite+aiosqlite:///./neural_sync.db` in environment
|
|
- No external setup required
|
|
|
|
## Architecture
|
|
|
|
### Backend Structure ([`backend/app/`](backend/app/))
|
|
|
|
- **[`main.py`](backend/app/main.py)**: FastAPI application with all endpoints
|
|
- Webhook handlers for Git and Lark events
|
|
- Signal ingestion with strategic impact analysis
|
|
- CRUD operations for experiments and context nodes
|
|
|
|
- **[`models.py`](backend/app/models.py)**: SQLAlchemy models with compatibility layer
|
|
- `Signal`: External signals with strategic analysis and generated tasks
|
|
- `ContextNode`: Knowledge units with vector embeddings and AI-extracted insights
|
|
- `Experiment`: Hypothesis-driven experiments with score tracking
|
|
- Note: Vector type and UUID have SQLite fallback for development
|
|
|
|
- **[`services/`](backend/app/services/)**: External integrations
|
|
- **[`llm.py`](backend/app/services/llm.py)**: Ollama client for embeddings, task breakdown, strategic evaluation, code audit
|
|
- **[`plane.py`](backend/app/services/plane.py)**: Plane PM tool integration (simulation mode without API key)
|
|
- **[`lark.py`](backend/app/services/lark.py)**: Lark/Feishu bot messaging with rich cards
|
|
- **[`fetcher.py`](backend/app/services/fetcher.py)**: HackerNews signal fetching
|
|
- **[`analyzer.py`](backend/app/services/analyzer.py)**: Fallback keyword-based impact scoring
|
|
|
|
### Frontend Structure ([`frontend/src/`](frontend/src/))
|
|
|
|
- **[`App.vue`](frontend/src/App.vue)**: Main layout with dark theme and horizontal navigation
|
|
- **[`components/SignalDashboard.vue`](frontend/src/components/SignalDashboard.vue)**: Complex command center with:
|
|
- Signal aggregation by source
|
|
- Competitive moat visualization with progress comparison
|
|
- ROI scorecard and radar charts
|
|
- Typewriter effect for AI analysis
|
|
- Polling-based status updates
|
|
- **[`components/ExperimentBoard.vue`](frontend/src/components/ExperimentBoard.vue)**: Experiment grid with auto-status based on scores
|
|
- **[`components/ContextManager.vue`](frontend/src/components/ContextManager.vue)**: Knowledge nodes with AI insight display (moat, tech_specs)
|
|
|
|
## Key Integration Points
|
|
|
|
### Plane Integration
|
|
- Environment variables: `PLANE_API_URL`, `PLANE_API_KEY`, `PLANE_WORKSPACE_SLUG`, `PLANE_PROJECT_ID`
|
|
- Without API key, runs in simulation mode (logs to console)
|
|
- Supports creating issues with labels, priority, and time estimates
|
|
- Status updates require State UUID lookup (not fully implemented in MVP)
|
|
|
|
### Ollama Integration
|
|
- Default host: `http://127.0.0.1:11434`
|
|
- Models used: `llama3` (general), `nomic-embed-text` (embeddings)
|
|
- All LLM calls are synchronous but wrapped in async endpoints
|
|
- Includes mock fallback responses for "Pixelle-Video" signals
|
|
|
|
### Git Webhook Flow
|
|
1. Commit message contains task ID (e.g., `#PROJ-123`)
|
|
2. Webhook extracts diff and message
|
|
3. [`llm.audit_code_change()`](backend/app/services/llm.py) evaluates against task requirement
|
|
4. If passed: updates Plane status, marks task Done in Signal
|
|
|
|
## Database Schema Notes
|
|
|
|
### Vector Embeddings
|
|
- PostgreSQL: Uses `Vector(768)` from pgvector
|
|
- SQLite: Fallback to JSON storage for development
|
|
- Embeddings generated via Ollama's `nomic-embed-text` model
|
|
|
|
### Migration Files
|
|
- Located in [`backend/alembic/versions/`](backend/alembic/versions/)
|
|
- Key migrations: initial tables, pgvector support, signal model updates
|
|
|
|
## Development Notes
|
|
|
|
- **CORS**: Currently allows all origins (`*`) - restrict for production
|
|
- **Database echo**: Enabled in development - set `echo=False` in [`database.py`](backend/app/database.py) for production
|
|
- **Frontend API**: Hardcoded to `http://127.0.0.1:8000` - configure via env var for deployment
|
|
- **Polling**: Signal dashboard polls every 5 seconds with smart diff detection to minimize re-renders
|
|
- **AI Analysis**: All LLM prompts are in [`llm.py`](backend/app/services/llm.py) with fallback mock data for specific keywords
|
|
|
|
## Testing and Validation
|
|
|
|
The system includes a mock fallback for certain signal types (e.g., "Pixelle-Video", "Civitai", "Sora") to demonstrate strategic analysis without requiring a live Ollama instance. These are defined in [`llm.py`](backend/app/services/llm.py) with hardcoded responses.
|