neural-sync/CLAUDE.md

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

# 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

# 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):

# 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/)

• 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: 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/: External integrations

  • llm.py: Ollama client for embeddings, task breakdown, strategic evaluation, code audit
  • plane.py: Plane PM tool integration (simulation mode without API key)
  • lark.py: Lark/Feishu bot messaging with rich cards
  • fetcher.py: HackerNews signal fetching
  • analyzer.py: Fallback keyword-based impact scoring

Frontend Structure (frontend/src/)

• App.vue: Main layout with dark theme and horizontal navigation
• 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: Experiment grid with auto-status based on scores
• 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() 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/
• 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 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 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 with hardcoded responses.