# 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.