linyuhang
/
PMFlow
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
PMFlow/CLAUDE.md

8.1 KiB
Raw Blame History

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

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

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

# Stop all services
./stop.sh

Backend Development

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

cd frontend-react
npm install
npm run dev          # Port 5174
npm run build
npm run preview

Vue 3 (Legacy):

cd frontend
npm install
npm run dev -- --host  # Port 5174
npm run build

Architecture

Backend Structure (backend/app/)

Core Architecture:

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

Key Systems:

  1. Multi-Tenancy (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, 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, 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):

    • 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:

  6. Integration Services:

Frontend Structure

React (frontend-react/src/):

  • pages/ - Page components (Login, Dashboard, Projects, Users, Skills)
  • components/ - Reusable UI components
  • api/ - API client wrappers
  • hooks/ - Custom React hooks (useUserRole)
  • Uses React Router with HashRouter, Tailwind CSS, Zustand for state

Vue 3 (frontend/src/):

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

  • 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

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

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
  • API Response: Standardized format via 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

Environment Variables

Key environment variables (see .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