PMFlow/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**PMFlow / Neural Sync** is an AI-native project management platform designed for small (10-50 person) AI/ML technical teams. The system has evolved into a multi-tenant, role-based PM operating system with:

- **Multi-tenant Architecture**: Complete data isolation with tenant_id filtering
- **RBAC**: Role-based access control with JWT authentication
- **Event-Driven Architecture**: Event bus with WebSocket real-time updates
- **AI-Native Features**: LangChain integration, skill management, intelligent task routing

### Dual Frontend Architecture

The project maintains two frontends:
- **Vue 3** (`frontend/`): Legacy Signal Dashboard with Naive UI
- **React 18** (`frontend-react/`): New PMFlow interface with shadcn/ui (recommended for new features)

## Common Development Commands

### Quick Start / Stop

```bash
# Start all services (backend + React frontend)
./start.sh

# Or use Python launcher (cross-platform)
python launcher.py

# Stop all services
./stop.sh
```

### Backend Development

```bash
cd backend

# Install dependencies (use project venv)
source ../venv/bin/activate  # On Windows: ../venv/Scripts/activate
pip install -r requirements.txt

# Run database migrations
alembic upgrade head

# Seed initial data (development)
python -m seed_projects.py

# Start backend server (dev mode with hot reload)
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Run specific file
python -m app.main
```

### Frontend Development

**React (PMFlow - Recommended)**:
```bash
cd frontend-react
npm install
npm run dev          # Port 5174
npm run build
npm run preview
```

**Vue 3 (Legacy)**:
```bash
cd frontend
npm install
npm run dev -- --host  # Port 5174
npm run build
```

## Architecture

### Backend Structure ([`backend/app/`](backend/app/))

**Core Architecture**:
- [`api/`](backend/app/api/) - API routes organized by module (auth, signals, users, sstc, etc.)
- [`core/`](backend/app/core/) - Configuration, logging, response formatting
- [`models/`](backend/app/models/) - SQLAlchemy ORM with multi-tenant base classes
- [`schemas/`](backend/app/schemas/) - Pydantic request/response models
- [`services/`](backend/app/services/) - Business logic layer
- [`dependencies/`](backend/app/dependencies/) - FastAPI dependency injection (auth, tenant filtering)
- [`config/`](backend/app/config/) - Configuration and AI prompts
- [`main.py`](backend/app/main.py) - FastAPI application entry point

**Key Systems**:

1. **Multi-Tenancy** ([`models/base.py`](backend/app/models/base.py)):
   - All models inherit from `Base` (includes `tenant_id`, `created_at`, `updated_at`)
   - `Tenant` model uses `BaseNoTenant` (no tenant_id)
   - All queries must filter by tenant_id via dependency injection

2. **Authentication** ([`services/auth.py`](backend/app/services/auth.py), [`dependencies/auth.py`](backend/app/dependencies/auth.py)):
   - JWT-based authentication with 24-hour expiration
   - RBAC with roles: BOSS, ADMIN, AI, FE, BE
   - Permission matrix for fine-grained access control
   - Use `require_roles()` and `get_current_user` dependencies

3. **Event System** ([`events.py`](backend/app/events.py), [`websocket.py`](backend/app/websocket.py)):
   - Event bus for pub/sub messaging
   - WebSocket manager with real-time broadcasting
   - Event types: signals, tasks, code reviews, audits, integrations

4. **Role Dispatcher** ([`dispatcher.py`](backend/app/dispatcher.py)):
   - Routes signals to appropriate roles (Boss, AI Engineer, Backend, Frontend)
   - Keyword and pattern-based routing with confidence scoring
   - Escalation logic for high-impact decisions

5. **AI Services**:
   - [`ai_service.py`](backend/app/services/ai_service.py) - LangChain integration
   - [`llm.py`](backend/app/services/llm.py) - Ollama/OpenAI client wrapper
   - [`skill_service.py`](backend/app/services/skill_service.py) - User skill management
   - [`config/ai_prompts.py`](backend/app/config/ai_prompts.py) - Centralized prompt templates

6. **Integration Services**:
   - [`plane.py`](backend/app/services/plane.py) - Plane PM tool integration
   - [`lark.py`](backend/app/services/lark.py) - Lark/Feishu messaging
   - [`auditor.py`](backend/app/services/auditor.py) - Code audit workflow
   - [`auto_merger.py`](backend/app/services/auto_merger.py) - Auto-merge logic

### Frontend Structure

**React** ([`frontend-react/src/`](frontend-react/src/)):
- [`pages/`](frontend-react/src/pages/) - Page components (Login, Dashboard, Projects, Users, Skills)
- [`components/`](frontend-react/src/components/) - Reusable UI components
- [`api/`](frontend-react/src/api/) - API client wrappers
- [`hooks/`](frontend-react/src/hooks/) - Custom React hooks (useUserRole)
- Uses React Router with HashRouter, Tailwind CSS, Zustand for state

**Vue 3** ([`frontend/src/`](frontend/src/)):
- [`pages/`](frontend/src/pages/) - Vue pages
- [`components/`](frontend/src/components/) - Vue components with Naive UI
- [`api/`](frontend/src/api/) - API client
- [`composables/`](frontend/src/composables/) - Vue composables
- [`stores/`](frontend/src/stores/) - Pinia stores

### Database Schema

**Multi-Tenant Models**:
- `User` - User accounts with roles (BOSS, ADMIN, AI, FE, BE)
- `Tenant` - Tenant isolation
- `Project` - Projects with tenant_id
- `Signal` - External signals with strategic analysis
- `Task` - Tasks linked to signals and projects
- `Skill` - User skills with proficiency levels
- `UserSkillBinding` - Many-to-many user-skill relationships
- `UserWorkload` - Real-time workload tracking

**Type Compatibility** ([`models/types.py`](backend/app/models/types.py)):
- PostgreSQL: JSONB, ARRAY, Vector (pgvector)
- SQLite: Fallback to JSON/text storage for development

## Key Integration Points

### Authentication Flow
1. Login via `/auth/login` returns JWT token
2. Include token in Authorization header: `Bearer <token>`
3. Use `get_current_user` dependency for protected routes
4. Use `require_roles("BOSS", "ADMIN")` for role-gated endpoints

### Multi-Tenant Queries
```python
from app.dependencies import get_tenant_id

@router.get("/items")
async def list_items(
    tenant_id: int = Depends(get_tenant_id),
    db: AsyncSession = Depends(get_db)
):
    result = await db.execute(
        select(Item).where(Item.tenant_id == tenant_id)
    )
```

### Event Broadcasting
```python
from app.events import get_event_bus, EventType

event_bus = get_event_bus()
await event_bus.publish(
    EventType.TASK_ASSIGNED,
    {"task_id": 123, "user_id": 456}
)
```

### WebSocket Events
- Events are automatically bridged to WebSocket clients
- Clients subscribe to event types for filtering
- Message format: `{"type": "event", "event_type": "...", "data": {...}, "timestamp": ...}`

## Development Notes

- **Database**: PostgreSQL with pgvector recommended; SQLite fallback for development
- **CORS**: Currently allows all origins (`*`) - restrict for production
- **Logging**: Structured logging via [`core/logging.py`](backend/app/core/logging.py)
- **API Response**: Standardized format via [`core/response.py`](backend/app/core/response.py)
- **AI Caching**: Redis-based caching for AI call results
- **AI Logging**: All AI calls logged to `ai_call_logs` table

## Ports and Endpoints

- **Backend API**: http://127.0.0.1:8000
- **API Docs**: http://127.0.0.1:8000/docs (Swagger UI)
- **React Frontend**: http://127.0.0.1:5174
- **Vue Frontend**: http://127.0.0.1:5173

## Environment Variables

Key environment variables (see [`.env.example`](frontend/.env.example)):
- `DATABASE_URL` - PostgreSQL/SQLite connection string
- `SECRET_KEY` - JWT signing key
- `OPENAI_API_KEY` - OpenAI API key for LangChain
- `REDIS_URL` - Redis connection for caching
- `PLANE_API_*` - Plane PM tool integration

## File Conventions

- **Pydantic Schemas**: Request/Response models in [`schemas/`](backend/app/schemas/)
- **SQLAlchemy Models**: Database models in [`models/`](backend/app/models/)
- **API Routes**: Route handlers in [`api/`](backend/app/api/)
- **Business Logic**: Services in [`services/`](backend/app/services/)
- **AI Prompts**: Centralized in [`config/ai_prompts.py`](backend/app/config/ai_prompts.py)