[P3] Feature: Entity Diagram Progress Tracker Tab

[frankbria]

[P2] Feature: Entity Diagram Progress Tracker Tab

Summary

Add a new "Entity Diagram" tab to the project dashboard that visualizes build progress at the entity level rather than the traditional file/directory level. This shifts the progress metaphor from "files and line changes" to "domain entities and their relationships"—aligning with CodeFRAME's entity-centric, agentic approach.

Problem Statement

Traditional IDEs track progress through:

• Individual files and directory structures
• Lines of code added/deleted
• Git diffs and file-based commits

This file-centric view doesn't map well to how autonomous agents think about work. CodeFRAME agents operate on entities (User, Task, Project, Agent, etc.) and their relationships. There's currently no visual representation of:

1. Which entities exist in the system
2. What development phase each entity is in (TDD red/green/refactor)
3. How entities connect to each other (APIs, dependencies)
4. Deployment status per entity or entity group

Proposed Solution

New Dashboard Tab: "Entity Diagram"

A visual diagram that:

1. Gets generated after discovery/specification documents (PRD, technical specs) are created
2. Displays entities as nodes with their names and relationships
3. Color-codes TDD status using a traffic-light progression
4. Shows deployment environment status

Entity Color States

Color	Phase	Meaning
Gray	Initial	Entity defined in specs, no implementation yet
Red	TDD Red	Tests exist but are failing
Green	TDD Green	Tests are passing (minimum viable implementation)
Purple	TDD Refactor	Code refactored and optimized
Blue	Deployed	Merged to main and deployed

Relationship Connectors (Arrows)

Arrows between entities represent:

• API relationships (one entity calls another)
• Data dependencies (foreign keys, references)
• Event flows (pub/sub, webhooks)
• Import/inheritance relationships

Arrow styles could differentiate relationship types (solid for API, dashed for events, etc.)

Deployment Status Indicator

A diagram-level badge or legend showing current deployment environment:

• Local/Dev - Running on developer machine
• Test - Deployed to test environment
• Staging - Deployed to staging environment
• Production - Live in production

Optionally, individual entities could show their deployment status if they deploy independently (microservices pattern).

User Experience

1. User submits PRD to CodeFRAME
2. Discovery agent generates specs including entity definitions
3. Entity Diagram auto-populates with gray nodes and connectors
4. As agents work on each entity:
   • Node turns red when test files are created (failing tests)
   • Node turns green when tests pass
   • Node turns purple when refactoring is complete
   • Node turns blue when deployed
5. User sees the application "light up" progressively as agents complete work

Technical Considerations

Data Model

May require new fields or a new table to track:

• entity_name: String identifier
• entity_status: Enum (gray, red, green, purple, blue)
• deployment_env: Enum (dev, test, staging, production)
• relationships: Array of connected entity IDs with relationship type

Diagram Rendering

Options to evaluate:

• React Flow - Interactive node-based diagrams (already popular in AI/agent UIs)
• Mermaid.js - Markdown-based diagrams (simpler, less interactive)
• D3.js - Maximum flexibility but more implementation effort
• Cytoscape.js - Graph visualization library

Recommend React Flow given the existing React/TypeScript frontend and need for real-time updates via WebSocket.

Integration Points

• Discovery Agent: Generates initial entity list and relationships from PRD/specs
• Test Worker: Updates status to red (tests created) → green (tests passing)
• Review Worker: Updates status to purple (refactor phase complete)
• Deployment/Git Integration: Updates status to blue (merged/deployed)
• WebSocket: Real-time status updates to dashboard

Acceptance Criteria

• New "Entity Diagram" tab appears in project dashboard after specs are generated
• Entities display as labeled nodes with correct initial (gray) coloring
• Relationship arrows render between connected entities
• Entity color updates in real-time as TDD phases complete
• Deployment environment indicator is visible and accurate
• Clicking an entity shows detail panel (tests, files, status history)
• Diagram is responsive and handles 20+ entities gracefully

Out of Scope (Future Enhancements)

• Entity grouping/clustering by domain or module
• Historical timeline view ("watch the build happen" replay)
• Drag-and-drop entity rearrangement
• Export diagram as image/PDF
• Entity-level deployment (for microservices)

Related

• Existing dashboard components: web-ui/src/components/
• WebSocket implementation: Real-time updates already exist for agents/blockers
• Quality Gates: Could trigger purple status transition
• Checkpoint/Recovery: Diagram state should be included in checkpoints

Labels

enhancement, P2-medium-beta, dashboard, ux

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#10 - feat(frontend): Multi-Agent State Management with React Context [merged]
#169 - feat(dashboard): Add dedicated tabs for Tasks, Quality Gates, and Metrics [merged]
#211 - feat(dashboard): Add PhaseProgress component for phase visualization [merged]
#213 - feat(planning): Add Generate Task Breakdown button to DiscoveryProgress [merged]
#215 - feat(dashboard): Add phase-aware task view integration (#16-6) [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[traycerai]

Plan

Observations

The codebase uses a React/TypeScript frontend with Next.js and a Python FastAPI backend. The dashboard implements a tab-based navigation system with real-time WebSocket updates. Currently, visualization is limited to recharts for charts—no graph/diagram libraries like React Flow exist yet. The data model tracks Projects, Tasks, Issues, and Agents, but there's no entity-level tracking system. Discovery agents generate PRDs and specs, but entity extraction from these documents isn't implemented. The WebSocket broadcast system is mature and can easily support new event types for entity status updates.

Approach

As a P3 post-beta feature, this implementation prioritizes a phased rollout that doesn't block core functionality. The approach follows a layered strategy: (1) extend the data model to track entities and their relationships with minimal schema changes, (2) create backend services to extract entities from PRD/specs during discovery, (3) add API endpoints and WebSocket broadcasts for entity status updates, (4) install React Flow and build the Entity Diagram tab component with graceful degradation, and (5) integrate with existing agent workers to update entity status as TDD phases progress. This aligns with CodeFRAME's entity-centric philosophy while leveraging existing infrastructure for real-time updates and dashboard tabs. The phased approach allows core features to remain unaffected while this visualization layer is developed and refined.

Implementation Steps

1. Backend Data Model Extension

Create Entity Tracking Schema

Add new database tables to track entities and their relationships. As a P3 feature, this uses a separate schema namespace to avoid impacting core tables:

• Create file:codeframe/persistence/migrations/migration_0XX_entity_tracking.py
  • Add entities table with columns: id, project_id, name, entity_type (User, Task, Project, etc.), status (gray/red/green/purple/blue), deployment_env (dev/test/staging/production), created_at, updated_at
  • Add entity_relationships table with columns: id, source_entity_id, target_entity_id, relationship_type (api/data/event/import), relationship_style (solid/dashed/dotted), created_at
  • Add indexes on project_id, status, and foreign keys
  • Mark migration as optional/feature-flagged to allow graceful degradation if feature is disabled

Extend Core Models

Update file:codeframe/core/models.py:

• Add EntityStatus enum with values: GRAY, RED, GREEN, PURPLE, BLUE
• Add DeploymentEnv enum with values: DEV, TEST, STAGING, PRODUCTION
• Add RelationshipType enum with values: API, DATA, EVENT, IMPORT
• Create Entity Pydantic model with fields matching the database schema
• Create EntityRelationship Pydantic model for relationship tracking
• Create EntityDiagramData response model containing entities list and relationships list

2. Entity Extraction Service

Create Entity Parser

Create file:codeframe/planning/entity_extractor.py:

• Implement extract_entities_from_prd(prd_text: str) -> List[Entity] using LLM to parse PRD and identify domain entities
• Implement extract_relationships(entities: List[Entity], prd_text: str) -> List[EntityRelationship] to identify connections between entities
• Use Claude API with structured prompts to extract entity names, types, and relationships from PRD sections
• Initialize all entities with status=GRAY (defined in specs, not implemented)
• Store extraction results in database via repository
• Include error handling and logging for extraction failures; gracefully degrade if extraction fails

Integrate with Discovery Agent

Update file:codeframe/agents/lead_agent.py:

• After PRD generation completes, call entity_extractor.extract_entities_from_prd() within a try-catch block
• Store extracted entities and relationships in database
• Broadcast entity_diagram_generated WebSocket event with entity count
• Log any extraction failures without blocking agent workflow

3. Backend API Endpoints

Create Entity Router

Create file:codeframe/ui/routers/entities.py:

• GET /api/projects/{project_id}/entities - Returns EntityDiagramData with all entities and relationships for the project; returns empty list if no entities exist
• PATCH /api/projects/{project_id}/entities/{entity_id}/status - Updates entity status (for manual overrides or agent updates)
• GET /api/projects/{project_id}/entities/{entity_id}/history - Returns status change history for an entity
• Add authentication via get_current_user dependency
• Add authorization checks via db.user_has_project_access()
• Include feature flag check to allow disabling entity endpoints if feature is not enabled

Create Entity Repository

Create file:codeframe/persistence/repositories/entity_repository.py:

• Implement create_entity(entity: Entity) -> int to insert entity records
• Implement get_entities_by_project(project_id: int) -> List[Entity] to fetch all entities for diagram
• Implement update_entity_status(entity_id: int, status: EntityStatus) -> None to update status
• Implement get_entity_relationships(project_id: int) -> List[EntityRelationship] to fetch relationships
• Implement create_relationship(relationship: EntityRelationship) -> int to store relationships

4. WebSocket Broadcasts for Entity Updates

Add Entity Broadcast Functions

Update file:codeframe/ui/websocket_broadcasts.py:

• Add broadcast_entity_status_changed(manager, project_id, entity_id, old_status, new_status, timestamp) to notify clients of status transitions
• Add broadcast_entity_diagram_generated(manager, project_id, entity_count, relationship_count) when diagram is first created
• Add broadcast_entity_deployed(manager, project_id, entity_id, deployment_env) when entity reaches blue status

Integrate with Agent Workers

Update agent workers to broadcast entity status changes:

• In file:codeframe/agents/test_worker_agent.py: When tests are created for an entity, update status to RED; when tests pass, update to GREEN
• In file:codeframe/agents/review_worker_agent.py: When refactoring completes, update status to PURPLE
• In file:codeframe/git/workflow_manager.py: When code is merged to main, update status to BLUE
• Each status change should call entity_repository.update_entity_status() and broadcast via WebSocket

5. Frontend Package Installation

Add React Flow Dependency

Update file:web-ui/package.json:

• Add "reactflow": "^11.10.0" to dependencies
• Add "@reactflow/core": "^11.10.0" and "@reactflow/background": "^11.3.0" for additional features
• Run npm install to install the new packages

6. Frontend Entity Diagram Component

Create Entity Node Component

Create file:web-ui/src/components/entity-diagram/EntityNode.tsx:

• Custom React Flow node component that displays entity name and status color
• Use color mapping: gray → bg-gray-400, red → bg-red-500, green → bg-green-500, purple → bg-purple-500, blue → bg-blue-500
• Display entity type as a badge (User, Task, Project, etc.)
• Add hover tooltip showing entity details and current status
• Make node clickable to show detail panel

Create Entity Diagram Component

Create file:web-ui/src/components/entity-diagram/EntityDiagram.tsx:

• Use React Flow's <ReactFlow> component with custom node types
• Fetch entity data from /api/projects/{projectId}/entities using SWR
• Transform API response into React Flow nodes and edges format
• Configure edge styles based on relationship type (solid for API, dashed for events, dotted for data)
• Add <Background> component for grid pattern
• Add <Controls> component for zoom/pan controls
• Implement auto-layout using React Flow's useNodesState and useEdgesState hooks
• Add deployment environment badge in top-right corner showing current env

Create Entity Detail Panel

Create file:web-ui/src/components/entity-diagram/EntityDetailPanel.tsx:

• Slide-out panel that appears when entity node is clicked
• Display entity name, type, current status, and status history
• Show list of related files and tests
• Show deployment status and environment
• Add "Close" button to dismiss panel

Add WebSocket Real-time Updates

Update file:web-ui/src/lib/websocketMessageMapper.ts:

• Add handlers for entity_status_changed, entity_diagram_generated, and entity_deployed message types
• Map WebSocket messages to state updates that trigger diagram re-render

7. Dashboard Tab Integration

Add Entity Diagram Tab

Update file:web-ui/src/types/dashboard.ts:

• Extend DashboardTab type to include 'entity-diagram'

Update file:web-ui/src/components/Dashboard.tsx:

• Add new tab button in navigation section (line ~305) with label "Entity Diagram" and data-testid="entity-diagram-tab"
• Add tab panel section (after line ~694) that renders <EntityDiagram projectId={projectId} /> when activeTab === 'entity-diagram'
• Only show tab when project phase is PLANNING or later (hide during discovery)
• Add conditional rendering: if no entities exist yet, show placeholder message "Entity diagram will appear after PRD generation"
• Wrap tab visibility in feature flag check to allow disabling tab if feature is not enabled

8. Type Definitions

Create Entity Types

Create file:web-ui/src/types/entity.ts:

• Define EntityStatus type: 'gray' | 'red' | 'green' | 'purple' | 'blue'
• Define DeploymentEnv type: 'dev' | 'test' | 'staging' | 'production'
• Define RelationshipType type: 'api' | 'data' | 'event' | 'import'
• Define Entity interface with fields: id, name, entity_type, status, deployment_env, created_at, updated_at
• Define EntityRelationship interface with fields: id, source_entity_id, target_entity_id, relationship_type, relationship_style
• Define EntityDiagramData interface with fields: entities: Entity[], relationships: EntityRelationship[]

9. API Client Integration

Add Entity API Methods

Update file:web-ui/src/lib/api.ts:

• Add getEntities(projectId: number) method that calls GET /api/projects/{projectId}/entities
• Add updateEntityStatus(projectId: number, entityId: number, status: EntityStatus) method
• Add getEntityHistory(projectId: number, entityId: number) method
• Export methods via entitiesApi object

10. Testing Considerations

Backend Tests

Create test files following existing patterns:

• file:tests/persistence/test_entity_repository.py - Test CRUD operations for entities and relationships
• file:tests/planning/test_entity_extractor.py - Test entity extraction from PRD text
• file:tests/ui/test_entity_router.py - Test API endpoints with authentication and authorization

Frontend Tests

Create test files following existing patterns:

• file:web-ui/__tests__/components/entity-diagram/EntityDiagram.test.tsx - Test diagram rendering and interactions
• file:web-ui/__tests__/components/entity-diagram/EntityNode.test.tsx - Test node component with different statuses
• file:web-ui/__tests__/integration/entity-diagram-realtime-updates.test.tsx - Test WebSocket updates

Architecture Diagram

sequenceDiagram
    participant User
    participant Dashboard
    participant EntityDiagram
    participant WebSocket
    participant API
    participant LeadAgent
    participant EntityExtractor
    participant TestWorker
    participant Database

    User->>Dashboard: Navigate to Entity Diagram tab
    Dashboard->>EntityDiagram: Render component
    EntityDiagram->>API: GET /api/projects/{id}/entities
    API->>Database: Fetch entities & relationships
    Database-->>API: Return entity data
    API-->>EntityDiagram: EntityDiagramData
    EntityDiagram->>EntityDiagram: Transform to React Flow format
    EntityDiagram-->>User: Display diagram (all gray nodes)

    Note over LeadAgent,EntityExtractor: After PRD Generation
    LeadAgent->>EntityExtractor: extract_entities_from_prd(prd_text)
    EntityExtractor->>Database: Store entities (status=GRAY)
    EntityExtractor->>WebSocket: broadcast_entity_diagram_generated
    WebSocket-->>EntityDiagram: entity_diagram_generated event
    EntityDiagram->>EntityDiagram: Refresh diagram

    Note over TestWorker,Database: During TDD Red Phase
    TestWorker->>Database: Update entity status to RED
    TestWorker->>WebSocket: broadcast_entity_status_changed
    WebSocket-->>EntityDiagram: entity_status_changed event
    EntityDiagram->>EntityDiagram: Update node color to red

    Note over TestWorker,Database: During TDD Green Phase
    TestWorker->>Database: Update entity status to GREEN
    TestWorker->>WebSocket: broadcast_entity_status_changed
    WebSocket-->>EntityDiagram: entity_status_changed event
    EntityDiagram->>EntityDiagram: Update node color to green

    User->>EntityDiagram: Click entity node
    EntityDiagram->>EntityDetailPanel: Show detail panel
    EntityDetailPanel->>API: GET /api/projects/{id}/entities/{entityId}/history
    API->>Database: Fetch status history
    Database-->>API: Return history
    API-->>EntityDetailPanel: Status history data
    EntityDetailPanel-->>User: Display entity details

Loading

Component Relationships

graph TD
    A[Dashboard.tsx] -->|activeTab='entity-diagram'| B[EntityDiagram.tsx]
    B -->|fetches data| C[API: /api/projects/id/entities]
    B -->|renders| D[EntityNode.tsx]
    B -->|listens to| E[WebSocket Client]
    D -->|onClick| F[EntityDetailPanel.tsx]
    F -->|fetches| G[API: /api/projects/id/entities/id/history]
    
    C -->|calls| H[entities.py router]
    H -->|uses| I[entity_repository.py]
    I -->|queries| J[Database: entities table]
    
    K[lead_agent.py] -->|after PRD| L[entity_extractor.py]
    L -->|stores| I
    L -->|broadcasts| M[websocket_broadcasts.py]
    
    N[test_worker_agent.py] -->|updates status| I
    N -->|broadcasts| M
    
    M -->|sends events| E
    
    style B fill:#e1f5ff
    style D fill:#e1f5ff
    style F fill:#e1f5ff
    style H fill:#fff4e1
    style I fill:#fff4e1
    style L fill:#fff4e1

Loading

Data Flow Summary

Phase	Trigger	Entity Status	Action
Discovery Complete	PRD generated	GRAY	entity_extractor parses PRD, creates entities, broadcasts entity_diagram_generated
TDD Red	Tests created	RED	test_worker_agent updates status, broadcasts entity_status_changed
TDD Green	Tests pass	GREEN	test_worker_agent updates status, broadcasts entity_status_changed
Refactor	Review complete	PURPLE	review_worker_agent updates status, broadcasts entity_status_changed
Deployed	Merged to main	BLUE	workflow_manager updates status, broadcasts entity_deployed

File Creation Checklist

Backend Files (Python)

• codeframe/persistence/migrations/migration_0XX_entity_tracking.py
• codeframe/persistence/repositories/entity_repository.py
• codeframe/planning/entity_extractor.py
• codeframe/ui/routers/entities.py
• codeframe/config/feature_flags.py (add entity diagram feature flag)
• tests/persistence/test_entity_repository.py
• tests/planning/test_entity_extractor.py
• tests/ui/test_entity_router.py

Frontend Files (TypeScript/React)

• web-ui/src/types/entity.ts
• web-ui/src/components/entity-diagram/EntityDiagram.tsx
• web-ui/src/components/entity-diagram/EntityNode.tsx
• web-ui/src/components/entity-diagram/EntityDetailPanel.tsx
• web-ui/src/lib/featureFlags.ts (add entity diagram feature flag)
• web-ui/__tests__/components/entity-diagram/EntityDiagram.test.tsx
• web-ui/__tests__/components/entity-diagram/EntityNode.test.tsx
• web-ui/__tests__/integration/entity-diagram-realtime-updates.test.tsx

Modified Files

• codeframe/core/models.py (add Entity models and enums)
• codeframe/ui/websocket_broadcasts.py (add entity broadcast functions)
• codeframe/agents/lead_agent.py (integrate entity extraction)
• codeframe/agents/test_worker_agent.py (update entity status)
• codeframe/agents/review_worker_agent.py (update entity status)
• codeframe/git/workflow_manager.py (update entity status on merge)
• web-ui/package.json (add React Flow dependency)
• web-ui/src/types/dashboard.ts (add entity-diagram tab type)
• web-ui/src/components/Dashboard.tsx (add tab navigation and panel)
• web-ui/src/lib/api.ts (add entity API methods)
• web-ui/src/lib/websocketMessageMapper.ts (add entity event handlers)

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase uses a React/TypeScript frontend with Next.js and a Python FastAPI backend. The dashboard implements a tab-based navigation system with real-time WebSocket updates. Currently, visualization is limited to `recharts` for charts—no graph/diagram libraries like React Flow exist yet. The data model tracks Projects, Tasks, Issues, and Agents, but there's no entity-level tracking system. Discovery agents generate PRDs and specs, but entity extraction from these documents isn't implemented. The WebSocket broadcast system is mature and can easily support new event types for entity status updates.

## Approach

As a P3 post-beta feature, this implementation prioritizes a phased rollout that doesn't block core functionality. The approach follows a layered strategy: (1) extend the data model to track entities and their relationships with minimal schema changes, (2) create backend services to extract entities from PRD/specs during discovery, (3) add API endpoints and WebSocket broadcasts for entity status updates, (4) install React Flow and build the Entity Diagram tab component with graceful degradation, and (5) integrate with existing agent workers to update entity status as TDD phases progress. This aligns with CodeFRAME's entity-centric philosophy while leveraging existing infrastructure for real-time updates and dashboard tabs. The phased approach allows core features to remain unaffected while this visualization layer is developed and refined.

## Implementation Steps

### 1. Backend Data Model Extension

**Create Entity Tracking Schema**

Add new database tables to track entities and their relationships. As a P3 feature, this uses a separate schema namespace to avoid impacting core tables:

- Create `file:codeframe/persistence/migrations/migration_0XX_entity_tracking.py`
  - Add `entities` table with columns: `id`, `project_id`, `name`, `entity_type` (User, Task, Project, etc.), `status` (gray/red/green/purple/blue), `deployment_env` (dev/test/staging/production), `created_at`, `updated_at`
  - Add `entity_relationships` table with columns: `id`, `source_entity_id`, `target_entity_id`, `relationship_type` (api/data/event/import), `relationship_style` (solid/dashed/dotted), `created_at`
  - Add indexes on `project_id`, `status`, and foreign keys
  - Mark migration as optional/feature-flagged to allow graceful degradation if feature is disabled

**Extend Core Models**

Update `file:codeframe/core/models.py`:

- Add `EntityStatus` enum with values: `GRAY`, `RED`, `GREEN`, `PURPLE`, `BLUE`
- Add `DeploymentEnv` enum with values: `DEV`, `TEST`, `STAGING`, `PRODUCTION`
- Add `RelationshipType` enum with values: `API`, `DATA`, `EVENT`, `IMPORT`
- Create `Entity` Pydantic model with fields matching the database schema
- Create `EntityRelationship` Pydantic model for relationship tracking
- Create `EntityDiagramData` response model containing entities list and relationships list

### 2. Entity Extraction Service

**Create Entity Parser**

Create `file:codeframe/planning/entity_extractor.py`:

- Implement `extract_entities_from_prd(prd_text: str) -> List[Entity]` using LLM to parse PRD and identify domain entities
- Implement `extract_relationships(entities: List[Entity], prd_text: str) -> List[EntityRelationship]` to identify connections between entities
- Use Claude API with structured prompts to extract entity names, types, and relationships from PRD sections
- Initialize all entities with `status=GRAY` (defined in specs, not implemented)
- Store extraction results in database via repository
- Include error handling and logging for extraction failures; gracefully degrade if extraction fails

**Integrate with Discovery Agent**

Update `file:codeframe/agents/lead_agent.py`:

- After PRD generation completes, call `entity_extractor.extract_entities_from_prd()` within a try-catch block
- Store extracted entities and relationships in database
- Broadcast `entity_diagram_generated` WebSocket event with entity count
- Log any extraction failures without blocking agent workflow

### 3. Backend API Endpoints

**Create Entity Router**

Create `file:codeframe/ui/routers/entities.py`:

- `GET /api/projects/{project_id}/entities` - Returns `EntityDiagramData` with all entities and relationships for the project; returns empty list if no entities exist
- `PATCH /api/projects/{project_id}/entities/{entity_id}/status` - Updates entity status (for manual overrides or agent updates)
- `GET /api/projects/{project_id}/entities/{entity_id}/history` - Returns status change history for an entity
- Add authentication via `get_current_user` dependency
- Add authorization checks via `db.user_has_project_access()`
- Include feature flag check to allow disabling entity endpoints if feature is not enabled

**Create Entity Repository**

Create `file:codeframe/persistence/repositories/entity_repository.py`:

- Implement `create_entity(entity: Entity) -> int` to insert entity records
- Implement `get_entities_by_project(project_id: int) -> List[Entity]` to fetch all entities for diagram
- Implement `update_entity_status(entity_id: int, status: EntityStatus) -> None` to update status
- Implement `get_entity_relationships(project_id: int) -> List[EntityRelationship]` to fetch relationships
- Implement `create_relationship(relationship: EntityRelationship) -> int` to store relationships

### 4. WebSocket Broadcasts for Entity Updates

**Add Entity Broadcast Functions**

Update `file:codeframe/ui/websocket_broadcasts.py`:

- Add `broadcast_entity_status_changed(manager, project_id, entity_id, old_status, new_status, timestamp)` to notify clients of status transitions
- Add `broadcast_entity_diagram_generated(manager, project_id, entity_count, relationship_count)` when diagram is first created
- Add `broadcast_entity_deployed(manager, project_id, entity_id, deployment_env)` when entity reaches blue status

**Integrate with Agent Workers**

Update agent workers to broadcast entity status changes:

- In `file:codeframe/agents/test_worker_agent.py`: When tests are created for an entity, update status to `RED`; when tests pass, update to `GREEN`
- In `file:codeframe/agents/review_worker_agent.py`: When refactoring completes, update status to `PURPLE`
- In `file:codeframe/git/workflow_manager.py`: When code is merged to main, update status to `BLUE`
- Each status change should call `entity_repository.update_entity_status()` and broadcast via WebSocket

### 5. Frontend Package Installation

**Add React Flow Dependency**

Update `file:web-ui/package.json`:

- Add `"reactflow": "^11.10.0"` to dependencies
- Add `"@reactflow/core": "^11.10.0"` and `"@reactflow/background": "^11.3.0"` for additional features
- Run `npm install` to install the new packages

### 6. Frontend Entity Diagram Component

**Create Entity Node Component**

Create `file:web-ui/src/components/entity-diagram/EntityNode.tsx`:

- Custom React Flow node component that displays entity name and status color
- Use color mapping: gray → `bg-gray-400`, red → `bg-red-500`, green → `bg-green-500`, purple → `bg-purple-500`, blue → `bg-blue-500`
- Display entity type as a badge (User, Task, Project, etc.)
- Add hover tooltip showing entity details and current status
- Make node clickable to show detail panel

**Create Entity Diagram Component**

Create `file:web-ui/src/components/entity-diagram/EntityDiagram.tsx`:

- Use React Flow's `<ReactFlow>` component with custom node types
- Fetch entity data from `/api/projects/{projectId}/entities` using SWR
- Transform API response into React Flow nodes and edges format
- Configure edge styles based on relationship type (solid for API, dashed for events, dotted for data)
- Add `<Background>` component for grid pattern
- Add `<Controls>` component for zoom/pan controls
- Implement auto-layout using React Flow's `useNodesState` and `useEdgesState` hooks
- Add deployment environment badge in top-right corner showing current env

**Create Entity Detail Panel**

Create `file:web-ui/src/components/entity-diagram/EntityDetailPanel.tsx`:

- Slide-out panel that appears when entity node is clicked
- Display entity name, type, current status, and status history
- Show list of related files and tests
- Show deployment status and environment
- Add "Close" button to dismiss panel

**Add WebSocket Real-time Updates**

Update `file:web-ui/src/lib/websocketMessageMapper.ts`:

- Add handlers for `entity_status_changed`, `entity_diagram_generated`, and `entity_deployed` message types
- Map WebSocket messages to state updates that trigger diagram re-render

### 7. Dashboard Tab Integration

**Add Entity Diagram Tab**

Update `file:web-ui/src/types/dashboard.ts`:

- Extend `DashboardTab` type to include `'entity-diagram'`

Update `file:web-ui/src/components/Dashboard.tsx`:

- Add new tab button in navigation section (line ~305) with label "Entity Diagram" and `data-testid="entity-diagram-tab"`
- Add tab panel section (after line ~694) that renders `<EntityDiagram projectId={projectId} />` when `activeTab === 'entity-diagram'`
- Only show tab when project phase is `PLANNING` or later (hide during discovery)
- Add conditional rendering: if no entities exist yet, show placeholder message "Entity diagram will appear after PRD generation"
- Wrap tab visibility in feature flag check to allow disabling tab if feature is not enabled

### 8. Type Definitions

**Create Entity Types**

Create `file:web-ui/src/types/entity.ts`:

- Define `EntityStatus` type: `'gray' | 'red' | 'green' | 'purple' | 'blue'`
- Define `DeploymentEnv` type: `'dev' | 'test' | 'staging' | 'production'`
- Define `RelationshipType` type: `'api' | 'data' | 'event' | 'import'`
- Define `Entity` interface with fields: `id`, `name`, `entity_type`, `status`, `deployment_env`, `created_at`, `updated_at`
- Define `EntityRelationship` interface with fields: `id`, `source_entity_id`, `target_entity_id`, `relationship_type`, `relationship_style`
- Define `EntityDiagramData` interface with fields: `entities: Entity[]`, `relationships: EntityRelationship[]`

### 9. API Client Integration

**Add Entity API Methods**

Update `file:web-ui/src/lib/api.ts`:

- Add `getEntities(projectId: number)` method that calls `GET /api/projects/{projectId}/entities`
- Add `updateEntityStatus(projectId: number, entityId: number, status: EntityStatus)` method
- Add `getEntityHistory(projectId: number, entityId: number)` method
- Export methods via `entitiesApi` object

### 10. Testing Considerations

**Backend Tests**

Create test files following existing patterns:

- `file:tests/persistence/test_entity_repository.py` - Test CRUD operations for entities and relationships
- `file:tests/planning/test_entity_extractor.py` - Test entity extraction from PRD text
- `file:tests/ui/test_entity_router.py` - Test API endpoints with authentication and authorization

**Frontend Tests**

Create test files following existing patterns:

- `file:web-ui/__tests__/components/entity-diagram/EntityDiagram.test.tsx` - Test diagram rendering and interactions
- `file:web-ui/__tests__/components/entity-diagram/EntityNode.test.tsx` - Test node component with different statuses
- `file:web-ui/__tests__/integration/entity-diagram-realtime-updates.test.tsx` - Test WebSocket updates

## Architecture Diagram

```mermaid
sequenceDiagram
    participant User
    participant Dashboard
    participant EntityDiagram
    participant WebSocket
    participant API
    participant LeadAgent
    participant EntityExtractor
    participant TestWorker
    participant Database

    User->>Dashboard: Navigate to Entity Diagram tab
    Dashboard->>EntityDiagram: Render component
    EntityDiagram->>API: GET /api/projects/{id}/entities
    API->>Database: Fetch entities & relationships
    Database-->>API: Return entity data
    API-->>EntityDiagram: EntityDiagramData
    EntityDiagram->>EntityDiagram: Transform to React Flow format
    EntityDiagram-->>User: Display diagram (all gray nodes)

    Note over LeadAgent,EntityExtractor: After PRD Generation
    LeadAgent->>EntityExtractor: extract_entities_from_prd(prd_text)
    EntityExtractor->>Database: Store entities (status=GRAY)
    EntityExtractor->>WebSocket: broadcast_entity_diagram_generated
    WebSocket-->>EntityDiagram: entity_diagram_generated event
    EntityDiagram->>EntityDiagram: Refresh diagram

    Note over TestWorker,Database: During TDD Red Phase
    TestWorker->>Database: Update entity status to RED
    TestWorker->>WebSocket: broadcast_entity_status_changed
    WebSocket-->>EntityDiagram: entity_status_changed event
    EntityDiagram->>EntityDiagram: Update node color to red

    Note over TestWorker,Database: During TDD Green Phase
    TestWorker->>Database: Update entity status to GREEN
    TestWorker->>WebSocket: broadcast_entity_status_changed
    WebSocket-->>EntityDiagram: entity_status_changed event
    EntityDiagram->>EntityDiagram: Update node color to green

    User->>EntityDiagram: Click entity node
    EntityDiagram->>EntityDetailPanel: Show detail panel
    EntityDetailPanel->>API: GET /api/projects/{id}/entities/{entityId}/history
    API->>Database: Fetch status history
    Database-->>API: Return history
    API-->>EntityDetailPanel: Status history data
    EntityDetailPanel-->>User: Display entity details
```

## Component Relationships

```mermaid
graph TD
    A[Dashboard.tsx] -->|activeTab='entity-diagram'| B[EntityDiagram.tsx]
    B -->|fetches data| C[API: /api/projects/id/entities]
    B -->|renders| D[EntityNode.tsx]
    B -->|listens to| E[WebSocket Client]
    D -->|onClick| F[EntityDetailPanel.tsx]
    F -->|fetches| G[API: /api/projects/id/entities/id/history]
    
    C -->|calls| H[entities.py router]
    H -->|uses| I[entity_repository.py]
    I -->|queries| J[Database: entities table]
    
    K[lead_agent.py] -->|after PRD| L[entity_extractor.py]
    L -->|stores| I
    L -->|broadcasts| M[websocket_broadcasts.py]
    
    N[test_worker_agent.py] -->|updates status| I
    N -->|broadcasts| M
    
    M -->|sends events| E
    
    style B fill:#e1f5ff
    style D fill:#e1f5ff
    style F fill:#e1f5ff
    style H fill:#fff4e1
    style I fill:#fff4e1
    style L fill:#fff4e1
```

## Data Flow Summary

| Phase | Trigger | Entity Status | Action |
|-------|---------|---------------|--------|
| Discovery Complete | PRD generated | GRAY | `entity_extractor` parses PRD, creates entities, broadcasts `entity_diagram_generated` |
| TDD Red | Tests created | RED | `test_worker_agent` updates status, broadcasts `entity_status_changed` |
| TDD Green | Tests pass | GREEN | `test_worker_agent` updates status, broadcasts `entity_status_changed` |
| Refactor | Review complete | PURPLE | `review_worker_agent` updates status, broadcasts `entity_status_changed` |
| Deployed | Merged to main | BLUE | `workflow_manager` updates status, broadcasts `entity_deployed` |

## File Creation Checklist

**Backend Files (Python)**
- `codeframe/persistence/migrations/migration_0XX_entity_tracking.py`
- `codeframe/persistence/repositories/entity_repository.py`
- `codeframe/planning/entity_extractor.py`
- `codeframe/ui/routers/entities.py`
- `codeframe/config/feature_flags.py` (add entity diagram feature flag)
- `tests/persistence/test_entity_repository.py`
- `tests/planning/test_entity_extractor.py`
- `tests/ui/test_entity_router.py`

**Frontend Files (TypeScript/React)**
- `web-ui/src/types/entity.ts`
- `web-ui/src/components/entity-diagram/EntityDiagram.tsx`
- `web-ui/src/components/entity-diagram/EntityNode.tsx`
- `web-ui/src/components/entity-diagram/EntityDetailPanel.tsx`
- `web-ui/src/lib/featureFlags.ts` (add entity diagram feature flag)
- `web-ui/__tests__/components/entity-diagram/EntityDiagram.test.tsx`
- `web-ui/__tests__/components/entity-diagram/EntityNode.test.tsx`
- `web-ui/__tests__/integration/entity-diagram-realtime-updates.test.tsx`

**Modified Files**
- `codeframe/core/models.py` (add Entity models and enums)
- `codeframe/ui/websocket_broadcasts.py` (add entity broadcast functions)
- `codeframe/agents/lead_agent.py` (integrate entity extraction)
- `codeframe/agents/test_worker_agent.py` (update entity status)
- `codeframe/agents/review_worker_agent.py` (update entity status)
- `codeframe/git/workflow_manager.py` (update entity status on merge)
- `web-ui/package.json` (add React Flow dependency)
- `web-ui/src/types/dashboard.ts` (add entity-diagram tab type)
- `web-ui/src/components/Dashboard.tsx` (add tab navigation and panel)
- `web-ui/src/lib/api.ts` (add entity API methods)
- `web-ui/src/lib/websocketMessageMapper.ts` (add entity event handlers)

---

Execution Information

Branch: main
Commit: 1260477

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[traycerai]

I have updated the Implementation Plan to reflect the recent changes in the ticket.

Previous Plan

Observations

The codebase uses a React/TypeScript frontend with Next.js and a Python FastAPI backend. The dashboard implements a tab-based navigation system with real-time WebSocket updates. Currently, visualization is limited to recharts for charts—no graph/diagram libraries like React Flow exist yet. The data model tracks Projects, Tasks, Issues, and Agents, but there's no entity-level tracking system. Discovery agents generate PRDs and specs, but entity extraction from these documents isn't implemented. The WebSocket broadcast system is mature and can easily support new event types for entity status updates.

Approach

The implementation follows a layered approach: (1) extend the data model to track entities and their relationships, (2) create backend services to extract entities from PRD/specs during discovery, (3) add API endpoints and WebSocket broadcasts for entity status updates, (4) install React Flow and build the Entity Diagram tab component, and (5) integrate with existing agent workers to update entity status as TDD phases progress. This aligns with CodeFRAME's entity-centric philosophy while leveraging existing infrastructure for real-time updates and dashboard tabs.

Implementation Steps

1. Backend Data Model Extension

Create Entity Tracking Schema

Add new database tables to track entities and their relationships:

• Create file:codeframe/persistence/migrations/migration_0XX_entity_tracking.py
  • Add entities table with columns: id, project_id, name, entity_type (User, Task, Project, etc.), status (gray/red/green/purple/blue), deployment_env (dev/test/staging/production), created_at, updated_at
  • Add entity_relationships table with columns: id, source_entity_id, target_entity_id, relationship_type (api/data/event/import), relationship_style (solid/dashed/dotted), created_at
  • Add indexes on project_id, status, and foreign keys

Extend Core Models

Update file:codeframe/core/models.py:

• Add EntityStatus enum with values: GRAY, RED, GREEN, PURPLE, BLUE
• Add DeploymentEnv enum with values: DEV, TEST, STAGING, PRODUCTION
• Add RelationshipType enum with values: API, DATA, EVENT, IMPORT
• Create Entity Pydantic model with fields matching the database schema
• Create EntityRelationship Pydantic model for relationship tracking
• Create EntityDiagramData response model containing entities list and relationships list

2. Entity Extraction Service

Create Entity Parser

Create file:codeframe/planning/entity_extractor.py:

• Implement extract_entities_from_prd(prd_text: str) -> List[Entity] using LLM to parse PRD and identify domain entities
• Implement extract_relationships(entities: List[Entity], prd_text: str) -> List[EntityRelationship] to identify connections between entities
• Use Claude API with structured prompts to extract entity names, types, and relationships from PRD sections
• Initialize all entities with status=GRAY (defined in specs, not implemented)
• Store extraction results in database via repository

Integrate with Discovery Agent

Update file:codeframe/agents/lead_agent.py:

• After PRD generation completes, call entity_extractor.extract_entities_from_prd()
• Store extracted entities and relationships in database
• Broadcast entity_diagram_generated WebSocket event with entity count

3. Backend API Endpoints

Create Entity Router

Create file:codeframe/ui/routers/entities.py:

• GET /api/projects/{project_id}/entities - Returns EntityDiagramData with all entities and relationships for the project
• PATCH /api/projects/{project_id}/entities/{entity_id}/status - Updates entity status (for manual overrides or agent updates)
• GET /api/projects/{project_id}/entities/{entity_id}/history - Returns status change history for an entity
• Add authentication via get_current_user dependency
• Add authorization checks via db.user_has_project_access()

Create Entity Repository

Create file:codeframe/persistence/repositories/entity_repository.py:

• Implement create_entity(entity: Entity) -> int to insert entity records
• Implement get_entities_by_project(project_id: int) -> List[Entity] to fetch all entities for diagram
• Implement update_entity_status(entity_id: int, status: EntityStatus) -> None to update status
• Implement get_entity_relationships(project_id: int) -> List[EntityRelationship] to fetch relationships
• Implement create_relationship(relationship: EntityRelationship) -> int to store relationships

4. WebSocket Broadcasts for Entity Updates

Add Entity Broadcast Functions

Update file:codeframe/ui/websocket_broadcasts.py:

• Add broadcast_entity_status_changed(manager, project_id, entity_id, old_status, new_status, timestamp) to notify clients of status transitions
• Add broadcast_entity_diagram_generated(manager, project_id, entity_count, relationship_count) when diagram is first created
• Add broadcast_entity_deployed(manager, project_id, entity_id, deployment_env) when entity reaches blue status

Integrate with Agent Workers

Update agent workers to broadcast entity status changes:

• In file:codeframe/agents/test_worker_agent.py: When tests are created for an entity, update status to RED; when tests pass, update to GREEN
• In file:codeframe/agents/review_worker_agent.py: When refactoring completes, update status to PURPLE
• In file:codeframe/git/workflow_manager.py: When code is merged to main, update status to BLUE
• Each status change should call entity_repository.update_entity_status() and broadcast via WebSocket

5. Frontend Package Installation

Add React Flow Dependency

Update file:web-ui/package.json:

• Add "reactflow": "^11.10.0" to dependencies
• Add "@reactflow/core": "^11.10.0" and "@reactflow/background": "^11.3.0" for additional features
• Run npm install to install the new packages

6. Frontend Entity Diagram Component

Create Entity Node Component

Create file:web-ui/src/components/entity-diagram/EntityNode.tsx:

• Custom React Flow node component that displays entity name and status color
• Use color mapping: gray → bg-gray-400, red → bg-red-500, green → bg-green-500, purple → bg-purple-500, blue → bg-blue-500
• Display entity type as a badge (User, Task, Project, etc.)
• Add hover tooltip showing entity details and current status
• Make node clickable to show detail panel

Create Entity Diagram Component

Create file:web-ui/src/components/entity-diagram/EntityDiagram.tsx:

• Use React Flow's <ReactFlow> component with custom node types
• Fetch entity data from /api/projects/{projectId}/entities using SWR
• Transform API response into React Flow nodes and edges format
• Configure edge styles based on relationship type (solid for API, dashed for events, dotted for data)
• Add <Background> component for grid pattern
• Add <Controls> component for zoom/pan controls
• Implement auto-layout using React Flow's useNodesState and useEdgesState hooks
• Add deployment environment badge in top-right corner showing current env

Create Entity Detail Panel

Create file:web-ui/src/components/entity-diagram/EntityDetailPanel.tsx:

• Slide-out panel that appears when entity node is clicked
• Display entity name, type, current status, and status history
• Show list of related files and tests
• Show deployment status and environment
• Add "Close" button to dismiss panel

Add WebSocket Real-time Updates

Update file:web-ui/src/lib/websocketMessageMapper.ts:

• Add handlers for entity_status_changed, entity_diagram_generated, and entity_deployed message types
• Map WebSocket messages to state updates that trigger diagram re-render

7. Dashboard Tab Integration

Add Entity Diagram Tab

Update file:web-ui/src/types/dashboard.ts:

• Extend DashboardTab type to include 'entity-diagram'

Update file:web-ui/src/components/Dashboard.tsx:

• Add new tab button in navigation section (line ~305) with label "Entity Diagram" and data-testid="entity-diagram-tab"
• Add tab panel section (after line ~694) that renders <EntityDiagram projectId={projectId} /> when activeTab === 'entity-diagram'
• Only show tab when project phase is PLANNING or later (hide during discovery)
• Add conditional rendering: if no entities exist yet, show placeholder message "Entity diagram will appear after PRD generation"

8. Type Definitions

Create Entity Types

Create file:web-ui/src/types/entity.ts:

• Define EntityStatus type: 'gray' | 'red' | 'green' | 'purple' | 'blue'
• Define DeploymentEnv type: 'dev' | 'test' | 'staging' | 'production'
• Define RelationshipType type: 'api' | 'data' | 'event' | 'import'
• Define Entity interface with fields: id, name, entity_type, status, deployment_env, created_at, updated_at
• Define EntityRelationship interface with fields: id, source_entity_id, target_entity_id, relationship_type, relationship_style
• Define EntityDiagramData interface with fields: entities: Entity[], relationships: EntityRelationship[]

9. API Client Integration

Add Entity API Methods

Update file:web-ui/src/lib/api.ts:

• Add getEntities(projectId: number) method that calls GET /api/projects/{projectId}/entities
• Add updateEntityStatus(projectId: number, entityId: number, status: EntityStatus) method
• Add getEntityHistory(projectId: number, entityId: number) method
• Export methods via entitiesApi object

10. Testing Considerations

Backend Tests

Create test files following existing patterns:

• file:tests/persistence/test_entity_repository.py - Test CRUD operations for entities and relationships
• file:tests/planning/test_entity_extractor.py - Test entity extraction from PRD text
• file:tests/ui/test_entity_router.py - Test API endpoints with authentication and authorization

Frontend Tests

Create test files following existing patterns:

• file:web-ui/__tests__/components/entity-diagram/EntityDiagram.test.tsx - Test diagram rendering and interactions
• file:web-ui/__tests__/components/entity-diagram/EntityNode.test.tsx - Test node component with different statuses
• file:web-ui/__tests__/integration/entity-diagram-realtime-updates.test.tsx - Test WebSocket updates

Architecture Diagram

sequenceDiagram
    participant User
    participant Dashboard
    participant EntityDiagram
    participant WebSocket
    participant API
    participant LeadAgent
    participant EntityExtractor
    participant TestWorker
    participant Database

    User->>Dashboard: Navigate to Entity Diagram tab
    Dashboard->>EntityDiagram: Render component
    EntityDiagram->>API: GET /api/projects/{id}/entities
    API->>Database: Fetch entities & relationships
    Database-->>API: Return entity data
    API-->>EntityDiagram: EntityDiagramData
    EntityDiagram->>EntityDiagram: Transform to React Flow format
    EntityDiagram-->>User: Display diagram (all gray nodes)

    Note over LeadAgent,EntityExtractor: After PRD Generation
    LeadAgent->>EntityExtractor: extract_entities_from_prd(prd_text)
    EntityExtractor->>Database: Store entities (status=GRAY)
    EntityExtractor->>WebSocket: broadcast_entity_diagram_generated
    WebSocket-->>EntityDiagram: entity_diagram_generated event
    EntityDiagram->>EntityDiagram: Refresh diagram

    Note over TestWorker,Database: During TDD Red Phase
    TestWorker->>Database: Update entity status to RED
    TestWorker->>WebSocket: broadcast_entity_status_changed
    WebSocket-->>EntityDiagram: entity_status_changed event
    EntityDiagram->>EntityDiagram: Update node color to red

    Note over TestWorker,Database: During TDD Green Phase
    TestWorker->>Database: Update entity status to GREEN
    TestWorker->>WebSocket: broadcast_entity_status_changed
    WebSocket-->>EntityDiagram: entity_status_changed event
    EntityDiagram->>EntityDiagram: Update node color to green

    User->>EntityDiagram: Click entity node
    EntityDiagram->>EntityDetailPanel: Show detail panel
    EntityDetailPanel->>API: GET /api/projects/{id}/entities/{entityId}/history
    API->>Database: Fetch status history
    Database-->>API: Return history
    API-->>EntityDetailPanel: Status history data
    EntityDetailPanel-->>User: Display entity details

Loading

Component Relationships

graph TD
    A[Dashboard.tsx] -->|activeTab='entity-diagram'| B[EntityDiagram.tsx]
    B -->|fetches data| C[API: /api/projects/id/entities]
    B -->|renders| D[EntityNode.tsx]
    B -->|listens to| E[WebSocket Client]
    D -->|onClick| F[EntityDetailPanel.tsx]
    F -->|fetches| G[API: /api/projects/id/entities/id/history]
    
    C -->|calls| H[entities.py router]
    H -->|uses| I[entity_repository.py]
    I -->|queries| J[Database: entities table]
    
    K[lead_agent.py] -->|after PRD| L[entity_extractor.py]
    L -->|stores| I
    L -->|broadcasts| M[websocket_broadcasts.py]
    
    N[test_worker_agent.py] -->|updates status| I
    N -->|broadcasts| M
    
    M -->|sends events| E
    
    style B fill:#e1f5ff
    style D fill:#e1f5ff
    style F fill:#e1f5ff
    style H fill:#fff4e1
    style I fill:#fff4e1
    style L fill:#fff4e1

Loading

Data Flow Summary

Phase	Trigger	Entity Status	Action
Discovery Complete	PRD generated	GRAY	entity_extractor parses PRD, creates entities, broadcasts entity_diagram_generated
TDD Red	Tests created	RED	test_worker_agent updates status, broadcasts entity_status_changed
TDD Green	Tests pass	GREEN	test_worker_agent updates status, broadcasts entity_status_changed
Refactor	Review complete	PURPLE	review_worker_agent updates status, broadcasts entity_status_changed
Deployed	Merged to main	BLUE	workflow_manager updates status, broadcasts entity_deployed

File Creation Checklist

Backend Files (Python)

• codeframe/persistence/migrations/migration_0XX_entity_tracking.py
• codeframe/persistence/repositories/entity_repository.py
• codeframe/planning/entity_extractor.py
• codeframe/ui/routers/entities.py
• tests/persistence/test_entity_repository.py
• tests/planning/test_entity_extractor.py
• tests/ui/test_entity_router.py

Frontend Files (TypeScript/React)

• web-ui/src/types/entity.ts
• web-ui/src/components/entity-diagram/EntityDiagram.tsx
• web-ui/src/components/entity-diagram/EntityNode.tsx
• web-ui/src/components/entity-diagram/EntityDetailPanel.tsx
• web-ui/__tests__/components/entity-diagram/EntityDiagram.test.tsx
• web-ui/__tests__/components/entity-diagram/EntityNode.test.tsx
• web-ui/__tests__/integration/entity-diagram-realtime-updates.test.tsx

Modified Files

• codeframe/core/models.py (add Entity models and enums)
• codeframe/ui/websocket_broadcasts.py (add entity broadcast functions)
• codeframe/agents/lead_agent.py (integrate entity extraction)
• codeframe/agents/test_worker_agent.py (update entity status)
• codeframe/agents/review_worker_agent.py (update entity status)
• codeframe/git/workflow_manager.py (update entity status on merge)
• web-ui/package.json (add React Flow dependency)
• web-ui/src/types/dashboard.ts (add entity-diagram tab type)
• web-ui/src/components/Dashboard.tsx (add tab navigation and panel)
• web-ui/src/lib/api.ts (add entity API methods)
• web-ui/src/lib/websocketMessageMapper.ts (add entity event handlers)

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase uses a React/TypeScript frontend with Next.js and a Python FastAPI backend. The dashboard implements a tab-based navigation system with real-time WebSocket updates. Currently, visualization is limited to `recharts` for charts—no graph/diagram libraries like React Flow exist yet. The data model tracks Projects, Tasks, Issues, and Agents, but there's no entity-level tracking system. Discovery agents generate PRDs and specs, but entity extraction from these documents isn't implemented. The WebSocket broadcast system is mature and can easily support new event types for entity status updates.

## Approach

The implementation follows a layered approach: (1) extend the data model to track entities and their relationships, (2) create backend services to extract entities from PRD/specs during discovery, (3) add API endpoints and WebSocket broadcasts for entity status updates, (4) install React Flow and build the Entity Diagram tab component, and (5) integrate with existing agent workers to update entity status as TDD phases progress. This aligns with CodeFRAME's entity-centric philosophy while leveraging existing infrastructure for real-time updates and dashboard tabs.

## Implementation Steps

### 1. Backend Data Model Extension

**Create Entity Tracking Schema**

Add new database tables to track entities and their relationships:

- Create `file:codeframe/persistence/migrations/migration_0XX_entity_tracking.py`
  - Add `entities` table with columns: `id`, `project_id`, `name`, `entity_type` (User, Task, Project, etc.), `status` (gray/red/green/purple/blue), `deployment_env` (dev/test/staging/production), `created_at`, `updated_at`
  - Add `entity_relationships` table with columns: `id`, `source_entity_id`, `target_entity_id`, `relationship_type` (api/data/event/import), `relationship_style` (solid/dashed/dotted), `created_at`
  - Add indexes on `project_id`, `status`, and foreign keys

**Extend Core Models**

Update `file:codeframe/core/models.py`:

- Add `EntityStatus` enum with values: `GRAY`, `RED`, `GREEN`, `PURPLE`, `BLUE`
- Add `DeploymentEnv` enum with values: `DEV`, `TEST`, `STAGING`, `PRODUCTION`
- Add `RelationshipType` enum with values: `API`, `DATA`, `EVENT`, `IMPORT`
- Create `Entity` Pydantic model with fields matching the database schema
- Create `EntityRelationship` Pydantic model for relationship tracking
- Create `EntityDiagramData` response model containing entities list and relationships list

### 2. Entity Extraction Service

**Create Entity Parser**

Create `file:codeframe/planning/entity_extractor.py`:

- Implement `extract_entities_from_prd(prd_text: str) -> List[Entity]` using LLM to parse PRD and identify domain entities
- Implement `extract_relationships(entities: List[Entity], prd_text: str) -> List[EntityRelationship]` to identify connections between entities
- Use Claude API with structured prompts to extract entity names, types, and relationships from PRD sections
- Initialize all entities with `status=GRAY` (defined in specs, not implemented)
- Store extraction results in database via repository

**Integrate with Discovery Agent**

Update `file:codeframe/agents/lead_agent.py`:

- After PRD generation completes, call `entity_extractor.extract_entities_from_prd()`
- Store extracted entities and relationships in database
- Broadcast `entity_diagram_generated` WebSocket event with entity count

### 3. Backend API Endpoints

**Create Entity Router**

Create `file:codeframe/ui/routers/entities.py`:

- `GET /api/projects/{project_id}/entities` - Returns `EntityDiagramData` with all entities and relationships for the project
- `PATCH /api/projects/{project_id}/entities/{entity_id}/status` - Updates entity status (for manual overrides or agent updates)
- `GET /api/projects/{project_id}/entities/{entity_id}/history` - Returns status change history for an entity
- Add authentication via `get_current_user` dependency
- Add authorization checks via `db.user_has_project_access()`

**Create Entity Repository**

Create `file:codeframe/persistence/repositories/entity_repository.py`:

- Implement `create_entity(entity: Entity) -> int` to insert entity records
- Implement `get_entities_by_project(project_id: int) -> List[Entity]` to fetch all entities for diagram
- Implement `update_entity_status(entity_id: int, status: EntityStatus) -> None` to update status
- Implement `get_entity_relationships(project_id: int) -> List[EntityRelationship]` to fetch relationships
- Implement `create_relationship(relationship: EntityRelationship) -> int` to store relationships

### 4. WebSocket Broadcasts for Entity Updates

**Add Entity Broadcast Functions**

Update `file:codeframe/ui/websocket_broadcasts.py`:

- Add `broadcast_entity_status_changed(manager, project_id, entity_id, old_status, new_status, timestamp)` to notify clients of status transitions
- Add `broadcast_entity_diagram_generated(manager, project_id, entity_count, relationship_count)` when diagram is first created
- Add `broadcast_entity_deployed(manager, project_id, entity_id, deployment_env)` when entity reaches blue status

**Integrate with Agent Workers**

Update agent workers to broadcast entity status changes:

- In `file:codeframe/agents/test_worker_agent.py`: When tests are created for an entity, update status to `RED`; when tests pass, update to `GREEN`
- In `file:codeframe/agents/review_worker_agent.py`: When refactoring completes, update status to `PURPLE`
- In `file:codeframe/git/workflow_manager.py`: When code is merged to main, update status to `BLUE`
- Each status change should call `entity_repository.update_entity_status()` and broadcast via WebSocket

### 5. Frontend Package Installation

**Add React Flow Dependency**

Update `file:web-ui/package.json`:

- Add `"reactflow": "^11.10.0"` to dependencies
- Add `"@reactflow/core": "^11.10.0"` and `"@reactflow/background": "^11.3.0"` for additional features
- Run `npm install` to install the new packages

### 6. Frontend Entity Diagram Component

**Create Entity Node Component**

Create `file:web-ui/src/components/entity-diagram/EntityNode.tsx`:

- Custom React Flow node component that displays entity name and status color
- Use color mapping: gray → `bg-gray-400`, red → `bg-red-500`, green → `bg-green-500`, purple → `bg-purple-500`, blue → `bg-blue-500`
- Display entity type as a badge (User, Task, Project, etc.)
- Add hover tooltip showing entity details and current status
- Make node clickable to show detail panel

**Create Entity Diagram Component**

Create `file:web-ui/src/components/entity-diagram/EntityDiagram.tsx`:

- Use React Flow's `<ReactFlow>` component with custom node types
- Fetch entity data from `/api/projects/{projectId}/entities` using SWR
- Transform API response into React Flow nodes and edges format
- Configure edge styles based on relationship type (solid for API, dashed for events, dotted for data)
- Add `<Background>` component for grid pattern
- Add `<Controls>` component for zoom/pan controls
- Implement auto-layout using React Flow's `useNodesState` and `useEdgesState` hooks
- Add deployment environment badge in top-right corner showing current env

**Create Entity Detail Panel**

Create `file:web-ui/src/components/entity-diagram/EntityDetailPanel.tsx`:

- Slide-out panel that appears when entity node is clicked
- Display entity name, type, current status, and status history
- Show list of related files and tests
- Show deployment status and environment
- Add "Close" button to dismiss panel

**Add WebSocket Real-time Updates**

Update `file:web-ui/src/lib/websocketMessageMapper.ts`:

- Add handlers for `entity_status_changed`, `entity_diagram_generated`, and `entity_deployed` message types
- Map WebSocket messages to state updates that trigger diagram re-render

### 7. Dashboard Tab Integration

**Add Entity Diagram Tab**

Update `file:web-ui/src/types/dashboard.ts`:

- Extend `DashboardTab` type to include `'entity-diagram'`

Update `file:web-ui/src/components/Dashboard.tsx`:

- Add new tab button in navigation section (line ~305) with label "Entity Diagram" and `data-testid="entity-diagram-tab"`
- Add tab panel section (after line ~694) that renders `<EntityDiagram projectId={projectId} />` when `activeTab === 'entity-diagram'`
- Only show tab when project phase is `PLANNING` or later (hide during discovery)
- Add conditional rendering: if no entities exist yet, show placeholder message "Entity diagram will appear after PRD generation"

### 8. Type Definitions

**Create Entity Types**

Create `file:web-ui/src/types/entity.ts`:

- Define `EntityStatus` type: `'gray' | 'red' | 'green' | 'purple' | 'blue'`
- Define `DeploymentEnv` type: `'dev' | 'test' | 'staging' | 'production'`
- Define `RelationshipType` type: `'api' | 'data' | 'event' | 'import'`
- Define `Entity` interface with fields: `id`, `name`, `entity_type`, `status`, `deployment_env`, `created_at`, `updated_at`
- Define `EntityRelationship` interface with fields: `id`, `source_entity_id`, `target_entity_id`, `relationship_type`, `relationship_style`
- Define `EntityDiagramData` interface with fields: `entities: Entity[]`, `relationships: EntityRelationship[]`

### 9. API Client Integration

**Add Entity API Methods**

Update `file:web-ui/src/lib/api.ts`:

- Add `getEntities(projectId: number)` method that calls `GET /api/projects/{projectId}/entities`
- Add `updateEntityStatus(projectId: number, entityId: number, status: EntityStatus)` method
- Add `getEntityHistory(projectId: number, entityId: number)` method
- Export methods via `entitiesApi` object

### 10. Testing Considerations

**Backend Tests**

Create test files following existing patterns:

- `file:tests/persistence/test_entity_repository.py` - Test CRUD operations for entities and relationships
- `file:tests/planning/test_entity_extractor.py` - Test entity extraction from PRD text
- `file:tests/ui/test_entity_router.py` - Test API endpoints with authentication and authorization

**Frontend Tests**

Create test files following existing patterns:

- `file:web-ui/__tests__/components/entity-diagram/EntityDiagram.test.tsx` - Test diagram rendering and interactions
- `file:web-ui/__tests__/components/entity-diagram/EntityNode.test.tsx` - Test node component with different statuses
- `file:web-ui/__tests__/integration/entity-diagram-realtime-updates.test.tsx` - Test WebSocket updates

## Architecture Diagram

```mermaid
sequenceDiagram
    participant User
    participant Dashboard
    participant EntityDiagram
    participant WebSocket
    participant API
    participant LeadAgent
    participant EntityExtractor
    participant TestWorker
    participant Database

    User->>Dashboard: Navigate to Entity Diagram tab
    Dashboard->>EntityDiagram: Render component
    EntityDiagram->>API: GET /api/projects/{id}/entities
    API->>Database: Fetch entities & relationships
    Database-->>API: Return entity data
    API-->>EntityDiagram: EntityDiagramData
    EntityDiagram->>EntityDiagram: Transform to React Flow format
    EntityDiagram-->>User: Display diagram (all gray nodes)

    Note over LeadAgent,EntityExtractor: After PRD Generation
    LeadAgent->>EntityExtractor: extract_entities_from_prd(prd_text)
    EntityExtractor->>Database: Store entities (status=GRAY)
    EntityExtractor->>WebSocket: broadcast_entity_diagram_generated
    WebSocket-->>EntityDiagram: entity_diagram_generated event
    EntityDiagram->>EntityDiagram: Refresh diagram

    Note over TestWorker,Database: During TDD Red Phase
    TestWorker->>Database: Update entity status to RED
    TestWorker->>WebSocket: broadcast_entity_status_changed
    WebSocket-->>EntityDiagram: entity_status_changed event
    EntityDiagram->>EntityDiagram: Update node color to red

    Note over TestWorker,Database: During TDD Green Phase
    TestWorker->>Database: Update entity status to GREEN
    TestWorker->>WebSocket: broadcast_entity_status_changed
    WebSocket-->>EntityDiagram: entity_status_changed event
    EntityDiagram->>EntityDiagram: Update node color to green

    User->>EntityDiagram: Click entity node
    EntityDiagram->>EntityDetailPanel: Show detail panel
    EntityDetailPanel->>API: GET /api/projects/{id}/entities/{entityId}/history
    API->>Database: Fetch status history
    Database-->>API: Return history
    API-->>EntityDetailPanel: Status history data
    EntityDetailPanel-->>User: Display entity details
```

## Component Relationships

```mermaid
graph TD
    A[Dashboard.tsx] -->|activeTab='entity-diagram'| B[EntityDiagram.tsx]
    B -->|fetches data| C[API: /api/projects/id/entities]
    B -->|renders| D[EntityNode.tsx]
    B -->|listens to| E[WebSocket Client]
    D -->|onClick| F[EntityDetailPanel.tsx]
    F -->|fetches| G[API: /api/projects/id/entities/id/history]
    
    C -->|calls| H[entities.py router]
    H -->|uses| I[entity_repository.py]
    I -->|queries| J[Database: entities table]
    
    K[lead_agent.py] -->|after PRD| L[entity_extractor.py]
    L -->|stores| I
    L -->|broadcasts| M[websocket_broadcasts.py]
    
    N[test_worker_agent.py] -->|updates status| I
    N -->|broadcasts| M
    
    M -->|sends events| E
    
    style B fill:#e1f5ff
    style D fill:#e1f5ff
    style F fill:#e1f5ff
    style H fill:#fff4e1
    style I fill:#fff4e1
    style L fill:#fff4e1
```

## Data Flow Summary

| Phase | Trigger | Entity Status | Action |
|-------|---------|---------------|--------|
| Discovery Complete | PRD generated | GRAY | `entity_extractor` parses PRD, creates entities, broadcasts `entity_diagram_generated` |
| TDD Red | Tests created | RED | `test_worker_agent` updates status, broadcasts `entity_status_changed` |
| TDD Green | Tests pass | GREEN | `test_worker_agent` updates status, broadcasts `entity_status_changed` |
| Refactor | Review complete | PURPLE | `review_worker_agent` updates status, broadcasts `entity_status_changed` |
| Deployed | Merged to main | BLUE | `workflow_manager` updates status, broadcasts `entity_deployed` |

## File Creation Checklist

**Backend Files (Python)**
- `codeframe/persistence/migrations/migration_0XX_entity_tracking.py`
- `codeframe/persistence/repositories/entity_repository.py`
- `codeframe/planning/entity_extractor.py`
- `codeframe/ui/routers/entities.py`
- `tests/persistence/test_entity_repository.py`
- `tests/planning/test_entity_extractor.py`
- `tests/ui/test_entity_router.py`

**Frontend Files (TypeScript/React)**
- `web-ui/src/types/entity.ts`
- `web-ui/src/components/entity-diagram/EntityDiagram.tsx`
- `web-ui/src/components/entity-diagram/EntityNode.tsx`
- `web-ui/src/components/entity-diagram/EntityDetailPanel.tsx`
- `web-ui/__tests__/components/entity-diagram/EntityDiagram.test.tsx`
- `web-ui/__tests__/components/entity-diagram/EntityNode.test.tsx`
- `web-ui/__tests__/integration/entity-diagram-realtime-updates.test.tsx`

**Modified Files**
- `codeframe/core/models.py` (add Entity models and enums)
- `codeframe/ui/websocket_broadcasts.py` (add entity broadcast functions)
- `codeframe/agents/lead_agent.py` (integrate entity extraction)
- `codeframe/agents/test_worker_agent.py` (update entity status)
- `codeframe/agents/review_worker_agent.py` (update entity status)
- `codeframe/git/workflow_manager.py` (update entity status on merge)
- `web-ui/package.json` (add React Flow dependency)
- `web-ui/src/types/dashboard.ts` (add entity-diagram tab type)
- `web-ui/src/components/Dashboard.tsx` (add tab navigation and panel)
- `web-ui/src/lib/api.ts` (add entity API methods)
- `web-ui/src/lib/websocketMessageMapper.ts` (add entity event handlers)

---

Execution Information

Branch: main
Commit: 759c232

New Plan

Observations

The codebase uses a React/TypeScript frontend with Next.js and a Python FastAPI backend. The dashboard implements a tab-based navigation system with real-time WebSocket updates. Currently, visualization is limited to recharts for charts—no graph/diagram libraries like React Flow exist yet. The data model tracks Projects, Tasks, Issues, and Agents, but there's no entity-level tracking system. Discovery agents generate PRDs and specs, but entity extraction from these documents isn't implemented. The WebSocket broadcast system is mature and can easily support new event types for entity status updates.

Approach

As a P3 post-beta feature, this implementation prioritizes a phased rollout that doesn't block core functionality. The approach follows a layered strategy: (1) extend the data model to track entities and their relationships with minimal schema changes, (2) create backend services to extract entities from PRD/specs during discovery, (3) add API endpoints and WebSocket broadcasts for entity status updates, (4) install React Flow and build the Entity Diagram tab component with graceful degradation, and (5) integrate with existing agent workers to update entity status as TDD phases progress. This aligns with CodeFRAME's entity-centric philosophy while leveraging existing infrastructure for real-time updates and dashboard tabs. The phased approach allows core features to remain unaffected while this visualization layer is developed and refined.

Implementation Steps

1. Backend Data Model Extension

Create Entity Tracking Schema

Add new database tables to track entities and their relationships. As a P3 feature, this uses a separate schema namespace to avoid impacting core tables:

• Create file:codeframe/persistence/migrations/migration_0XX_entity_tracking.py
  • Add entities table with columns: id, project_id, name, entity_type (User, Task, Project, etc.), status (gray/red/green/purple/blue), deployment_env (dev/test/staging/production), created_at, updated_at
  • Add entity_relationships table with columns: id, source_entity_id, target_entity_id, relationship_type (api/data/event/import), relationship_style (solid/dashed/dotted), created_at
  • Add indexes on project_id, status, and foreign keys
  • Mark migration as optional/feature-flagged to allow graceful degradation if feature is disabled

Extend Core Models

Update file:codeframe/core/models.py:

• Add EntityStatus enum with values: GRAY, RED, GREEN, PURPLE, BLUE
• Add DeploymentEnv enum with values: DEV, TEST, STAGING, PRODUCTION
• Add RelationshipType enum with values: API, DATA, EVENT, IMPORT
• Create Entity Pydantic model with fields matching the database schema
• Create EntityRelationship Pydantic model for relationship tracking
• Create EntityDiagramData response model containing entities list and relationships list

2. Entity Extraction Service

Create Entity Parser

Create file:codeframe/planning/entity_extractor.py:

• Implement extract_entities_from_prd(prd_text: str) -> List[Entity] using LLM to parse PRD and identify domain entities
• Implement extract_relationships(entities: List[Entity], prd_text: str) -> List[EntityRelationship] to identify connections between entities
• Use Claude API with structured prompts to extract entity names, types, and relationships from PRD sections
• Initialize all entities with status=GRAY (defined in specs, not implemented)
• Store extraction results in database via repository
• Include error handling and logging for extraction failures; gracefully degrade if extraction fails

Integrate with Discovery Agent

Update file:codeframe/agents/lead_agent.py:

• After PRD generation completes, call entity_extractor.extract_entities_from_prd() within a try-catch block
• Store extracted entities and relationships in database
• Broadcast entity_diagram_generated WebSocket event with entity count
• Log any extraction failures without blocking agent workflow

3. Backend API Endpoints

Create Entity Router

Create file:codeframe/ui/routers/entities.py:

• GET /api/projects/{project_id}/entities - Returns EntityDiagramData with all entities and relationships for the project; returns empty list if no entities exist
• PATCH /api/projects/{project_id}/entities/{entity_id}/status - Updates entity status (for manual overrides or agent updates)
• GET /api/projects/{project_id}/entities/{entity_id}/history - Returns status change history for an entity
• Add authentication via get_current_user dependency
• Add authorization checks via db.user_has_project_access()
• Include feature flag check to allow disabling entity endpoints if feature is not enabled

Create Entity Repository

Create file:codeframe/persistence/repositories/entity_repository.py:

• Implement create_entity(entity: Entity) -> int to insert entity records
• Implement get_entities_by_project(project_id: int) -> List[Entity] to fetch all entities for diagram
• Implement update_entity_status(entity_id: int, status: EntityStatus) -> None to update status
• Implement get_entity_relationships(project_id: int) -> List[EntityRelationship] to fetch relationships
• Implement create_relationship(relationship: EntityRelationship) -> int to store relationships

4. WebSocket Broadcasts for Entity Updates

Add Entity Broadcast Functions

Update file:codeframe/ui/websocket_broadcasts.py:

• Add broadcast_entity_status_changed(manager, project_id, entity_id, old_status, new_status, timestamp) to notify clients of status transitions
• Add broadcast_entity_diagram_generated(manager, project_id, entity_count, relationship_count) when diagram is first created
• Add broadcast_entity_deployed(manager, project_id, entity_id, deployment_env) when entity reaches blue status

Integrate with Agent Workers

Update agent workers to broadcast entity status changes:

• In file:codeframe/agents/test_worker_agent.py: When tests are created for an entity, update status to RED; when tests pass, update to GREEN
• In file:codeframe/agents/review_worker_agent.py: When refactoring completes, update status to PURPLE
• In file:codeframe/git/workflow_manager.py: When code is merged to main, update status to BLUE
• Each status change should call entity_repository.update_entity_status() and broadcast via WebSocket

5. Frontend Package Installation

Add React Flow Dependency

Update file:web-ui/package.json:

• Add "reactflow": "^11.10.0" to dependencies
• Add "@reactflow/core": "^11.10.0" and "@reactflow/background": "^11.3.0" for additional features
• Run npm install to install the new packages

6. Frontend Entity Diagram Component

Create Entity Node Component

Create file:web-ui/src/components/entity-diagram/EntityNode.tsx:

• Custom React Flow node component that displays entity name and status color
• Use color mapping: gray → bg-gray-400, red → bg-red-500, green → bg-green-500, purple → bg-purple-500, blue → bg-blue-500
• Display entity type as a badge (User, Task, Project, etc.)
• Add hover tooltip showing entity details and current status
• Make node clickable to show detail panel

Create Entity Diagram Component

Create file:web-ui/src/components/entity-diagram/EntityDiagram.tsx:

• Use React Flow's <ReactFlow> component with custom node types
• Fetch entity data from /api/projects/{projectId}/entities using SWR
• Transform API response into React Flow nodes and edges format
• Configure edge styles based on relationship type (solid for API, dashed for events, dotted for data)
• Add <Background> component for grid pattern
• Add <Controls> component for zoom/pan controls
• Implement auto-layout using React Flow's useNodesState and useEdgesState hooks
• Add deployment environment badge in top-right corner showing current env

Create Entity Detail Panel

Create file:web-ui/src/components/entity-diagram/EntityDetailPanel.tsx:

• Slide-out panel that appears when entity node is clicked
• Display entity name, type, current status, and status history
• Show list of related files and tests
• Show deployment status and environment
• Add "Close" button to dismiss panel

Add WebSocket Real-time Updates

Update file:web-ui/src/lib/websocketMessageMapper.ts:

• Add handlers for entity_status_changed, entity_diagram_generated, and entity_deployed message types
• Map WebSocket messages to state updates that trigger diagram re-render

7. Dashboard Tab Integration

Add Entity Diagram Tab

Update file:web-ui/src/types/dashboard.ts:

• Extend DashboardTab type to include 'entity-diagram'

Update file:web-ui/src/components/Dashboard.tsx:

• Add new tab button in navigation section (line ~305) with label "Entity Diagram" and data-testid="entity-diagram-tab"
• Add tab panel section (after line ~694) that renders <EntityDiagram projectId={projectId} /> when activeTab === 'entity-diagram'
• Only show tab when project phase is PLANNING or later (hide during discovery)
• Add conditional rendering: if no entities exist yet, show placeholder message "Entity diagram will appear after PRD generation"
• Wrap tab visibility in feature flag check to allow disabling tab if feature is not enabled

8. Type Definitions

Create Entity Types

Create file:web-ui/src/types/entity.ts:

• Define EntityStatus type: 'gray' | 'red' | 'green' | 'purple' | 'blue'
• Define DeploymentEnv type: 'dev' | 'test' | 'staging' | 'production'
• Define RelationshipType type: 'api' | 'data' | 'event' | 'import'
• Define Entity interface with fields: id, name, entity_type, status, deployment_env, created_at, updated_at
• Define EntityRelationship interface with fields: id, source_entity_id, target_entity_id, relationship_type, relationship_style
• Define EntityDiagramData interface with fields: entities: Entity[], relationships: EntityRelationship[]

9. API Client Integration

Add Entity API Methods

Update file:web-ui/src/lib/api.ts:

• Add getEntities(projectId: number) method that calls GET /api/projects/{projectId}/entities
• Add updateEntityStatus(projectId: number, entityId: number, status: EntityStatus) method
• Add getEntityHistory(projectId: number, entityId: number) method
• Export methods via entitiesApi object

10. Testing Considerations

Backend Tests

Create test files following existing patterns:

• file:tests/persistence/test_entity_repository.py - Test CRUD operations for entities and relationships
• file:tests/planning/test_entity_extractor.py - Test entity extraction from PRD text
• file:tests/ui/test_entity_router.py - Test API endpoints with authentication and authorization

Frontend Tests

Create test files following existing patterns:

• file:web-ui/__tests__/components/entity-diagram/EntityDiagram.test.tsx - Test diagram rendering and interactions
• file:web-ui/__tests__/components/entity-diagram/EntityNode.test.tsx - Test node component with different statuses
• file:web-ui/__tests__/integration/entity-diagram-realtime-updates.test.tsx - Test WebSocket updates

Architecture Diagram

sequenceDiagram
    participant User
    participant Dashboard
    participant EntityDiagram
    participant WebSocket
    participant API
    participant LeadAgent
    participant EntityExtractor
    participant TestWorker
    participant Database

    User->>Dashboard: Navigate to Entity Diagram tab
    Dashboard->>EntityDiagram: Render component
    EntityDiagram->>API: GET /api/projects/{id}/entities
    API->>Database: Fetch entities & relationships
    Database-->>API: Return entity data
    API-->>EntityDiagram: EntityDiagramData
    EntityDiagram->>EntityDiagram: Transform to React Flow format
    EntityDiagram-->>User: Display diagram (all gray nodes)

    Note over LeadAgent,EntityExtractor: After PRD Generation
    LeadAgent->>EntityExtractor: extract_entities_from_prd(prd_text)
    EntityExtractor->>Database: Store entities (status=GRAY)
    EntityExtractor->>WebSocket: broadcast_entity_diagram_generated
    WebSocket-->>EntityDiagram: entity_diagram_generated event
    EntityDiagram->>EntityDiagram: Refresh diagram

    Note over TestWorker,Database: During TDD Red Phase
    TestWorker->>Database: Update entity status to RED
    TestWorker->>WebSocket: broadcast_entity_status_changed
    WebSocket-->>EntityDiagram: entity_status_changed event
    EntityDiagram->>EntityDiagram: Update node color to red

    Note over TestWorker,Database: During TDD Green Phase
    TestWorker->>Database: Update entity status to GREEN
    TestWorker->>WebSocket: broadcast_entity_status_changed
    WebSocket-->>EntityDiagram: entity_status_changed event
    EntityDiagram->>EntityDiagram: Update node color to green

    User->>EntityDiagram: Click entity node
    EntityDiagram->>EntityDetailPanel: Show detail panel
    EntityDetailPanel->>API: GET /api/projects/{id}/entities/{entityId}/history
    API->>Database: Fetch status history
    Database-->>API: Return history
    API-->>EntityDetailPanel: Status history data
    EntityDetailPanel-->>User: Display entity details

Loading

Component Relationships

graph TD
    A[Dashboard.tsx] -->|activeTab='entity-diagram'| B[EntityDiagram.tsx]
    B -->|fetches data| C[API: /api/projects/id/entities]
    B -->|renders| D[EntityNode.tsx]
    B -->|listens to| E[WebSocket Client]
    D -->|onClick| F[EntityDetailPanel.tsx]
    F -->|fetches| G[API: /api/projects/id/entities/id/history]
    
    C -->|calls| H[entities.py router]
    H -->|uses| I[entity_repository.py]
    I -->|queries| J[Database: entities table]
    
    K[lead_agent.py] -->|after PRD| L[entity_extractor.py]
    L -->|stores| I
    L -->|broadcasts| M[websocket_broadcasts.py]
    
    N[test_worker_agent.py] -->|updates status| I
    N -->|broadcasts| M
    
    M -->|sends events| E
    
    style B fill:#e1f5ff
    style D fill:#e1f5ff
    style F fill:#e1f5ff
    style H fill:#fff4e1
    style I fill:#fff4e1
    style L fill:#fff4e1

Loading

Data Flow Summary

Phase	Trigger	Entity Status	Action
Discovery Complete	PRD generated	GRAY	entity_extractor parses PRD, creates entities, broadcasts entity_diagram_generated
TDD Red	Tests created	RED	test_worker_agent updates status, broadcasts entity_status_changed
TDD Green	Tests pass	GREEN	test_worker_agent updates status, broadcasts entity_status_changed
Refactor	Review complete	PURPLE	review_worker_agent updates status, broadcasts entity_status_changed
Deployed	Merged to main	BLUE	workflow_manager updates status, broadcasts entity_deployed

File Creation Checklist

Backend Files (Python)

• codeframe/persistence/migrations/migration_0XX_entity_tracking.py
• codeframe/persistence/repositories/entity_repository.py
• codeframe/planning/entity_extractor.py
• codeframe/ui/routers/entities.py
• codeframe/config/feature_flags.py (add entity diagram feature flag)
• tests/persistence/test_entity_repository.py
• tests/planning/test_entity_extractor.py
• tests/ui/test_entity_router.py

Frontend Files (TypeScript/React)

• web-ui/src/types/entity.ts
• web-ui/src/components/entity-diagram/EntityDiagram.tsx
• web-ui/src/components/entity-diagram/EntityNode.tsx
• web-ui/src/components/entity-diagram/EntityDetailPanel.tsx
• web-ui/src/lib/featureFlags.ts (add entity diagram feature flag)
• web-ui/__tests__/components/entity-diagram/EntityDiagram.test.tsx
• web-ui/__tests__/components/entity-diagram/EntityNode.test.tsx
• web-ui/__tests__/integration/entity-diagram-realtime-updates.test.tsx

Modified Files

• codeframe/core/models.py (add Entity models and enums)
• codeframe/ui/websocket_broadcasts.py (add entity broadcast functions)
• codeframe/agents/lead_agent.py (integrate entity extraction)
• codeframe/agents/test_worker_agent.py (update entity status)
• codeframe/agents/review_worker_agent.py (update entity status)
• codeframe/git/workflow_manager.py (update entity status on merge)
• web-ui/package.json (add React Flow dependency)
• web-ui/src/types/dashboard.ts (add entity-diagram tab type)
• web-ui/src/components/Dashboard.tsx (add tab navigation and panel)
• web-ui/src/lib/api.ts (add entity API methods)
• web-ui/src/lib/websocketMessageMapper.ts (add entity event handlers)

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase uses a React/TypeScript frontend with Next.js and a Python FastAPI backend. The dashboard implements a tab-based navigation system with real-time WebSocket updates. Currently, visualization is limited to `recharts` for charts—no graph/diagram libraries like React Flow exist yet. The data model tracks Projects, Tasks, Issues, and Agents, but there's no entity-level tracking system. Discovery agents generate PRDs and specs, but entity extraction from these documents isn't implemented. The WebSocket broadcast system is mature and can easily support new event types for entity status updates.

## Approach

As a P3 post-beta feature, this implementation prioritizes a phased rollout that doesn't block core functionality. The approach follows a layered strategy: (1) extend the data model to track entities and their relationships with minimal schema changes, (2) create backend services to extract entities from PRD/specs during discovery, (3) add API endpoints and WebSocket broadcasts for entity status updates, (4) install React Flow and build the Entity Diagram tab component with graceful degradation, and (5) integrate with existing agent workers to update entity status as TDD phases progress. This aligns with CodeFRAME's entity-centric philosophy while leveraging existing infrastructure for real-time updates and dashboard tabs. The phased approach allows core features to remain unaffected while this visualization layer is developed and refined.

## Implementation Steps

### 1. Backend Data Model Extension

**Create Entity Tracking Schema**

Add new database tables to track entities and their relationships. As a P3 feature, this uses a separate schema namespace to avoid impacting core tables:

- Create `file:codeframe/persistence/migrations/migration_0XX_entity_tracking.py`
  - Add `entities` table with columns: `id`, `project_id`, `name`, `entity_type` (User, Task, Project, etc.), `status` (gray/red/green/purple/blue), `deployment_env` (dev/test/staging/production), `created_at`, `updated_at`
  - Add `entity_relationships` table with columns: `id`, `source_entity_id`, `target_entity_id`, `relationship_type` (api/data/event/import), `relationship_style` (solid/dashed/dotted), `created_at`
  - Add indexes on `project_id`, `status`, and foreign keys
  - Mark migration as optional/feature-flagged to allow graceful degradation if feature is disabled

**Extend Core Models**

Update `file:codeframe/core/models.py`:

- Add `EntityStatus` enum with values: `GRAY`, `RED`, `GREEN`, `PURPLE`, `BLUE`
- Add `DeploymentEnv` enum with values: `DEV`, `TEST`, `STAGING`, `PRODUCTION`
- Add `RelationshipType` enum with values: `API`, `DATA`, `EVENT`, `IMPORT`
- Create `Entity` Pydantic model with fields matching the database schema
- Create `EntityRelationship` Pydantic model for relationship tracking
- Create `EntityDiagramData` response model containing entities list and relationships list

### 2. Entity Extraction Service

**Create Entity Parser**

Create `file:codeframe/planning/entity_extractor.py`:

- Implement `extract_entities_from_prd(prd_text: str) -> List[Entity]` using LLM to parse PRD and identify domain entities
- Implement `extract_relationships(entities: List[Entity], prd_text: str) -> List[EntityRelationship]` to identify connections between entities
- Use Claude API with structured prompts to extract entity names, types, and relationships from PRD sections
- Initialize all entities with `status=GRAY` (defined in specs, not implemented)
- Store extraction results in database via repository
- Include error handling and logging for extraction failures; gracefully degrade if extraction fails

**Integrate with Discovery Agent**

Update `file:codeframe/agents/lead_agent.py`:

- After PRD generation completes, call `entity_extractor.extract_entities_from_prd()` within a try-catch block
- Store extracted entities and relationships in database
- Broadcast `entity_diagram_generated` WebSocket event with entity count
- Log any extraction failures without blocking agent workflow

### 3. Backend API Endpoints

**Create Entity Router**

Create `file:codeframe/ui/routers/entities.py`:

- `GET /api/projects/{project_id}/entities` - Returns `EntityDiagramData` with all entities and relationships for the project; returns empty list if no entities exist
- `PATCH /api/projects/{project_id}/entities/{entity_id}/status` - Updates entity status (for manual overrides or agent updates)
- `GET /api/projects/{project_id}/entities/{entity_id}/history` - Returns status change history for an entity
- Add authentication via `get_current_user` dependency
- Add authorization checks via `db.user_has_project_access()`
- Include feature flag check to allow disabling entity endpoints if feature is not enabled

**Create Entity Repository**

Create `file:codeframe/persistence/repositories/entity_repository.py`:

- Implement `create_entity(entity: Entity) -> int` to insert entity records
- Implement `get_entities_by_project(project_id: int) -> List[Entity]` to fetch all entities for diagram
- Implement `update_entity_status(entity_id: int, status: EntityStatus) -> None` to update status
- Implement `get_entity_relationships(project_id: int) -> List[EntityRelationship]` to fetch relationships
- Implement `create_relationship(relationship: EntityRelationship) -> int` to store relationships

### 4. WebSocket Broadcasts for Entity Updates

**Add Entity Broadcast Functions**

Update `file:codeframe/ui/websocket_broadcasts.py`:

- Add `broadcast_entity_status_changed(manager, project_id, entity_id, old_status, new_status, timestamp)` to notify clients of status transitions
- Add `broadcast_entity_diagram_generated(manager, project_id, entity_count, relationship_count)` when diagram is first created
- Add `broadcast_entity_deployed(manager, project_id, entity_id, deployment_env)` when entity reaches blue status

**Integrate with Agent Workers**

Update agent workers to broadcast entity status changes:

- In `file:codeframe/agents/test_worker_agent.py`: When tests are created for an entity, update status to `RED`; when tests pass, update to `GREEN`
- In `file:codeframe/agents/review_worker_agent.py`: When refactoring completes, update status to `PURPLE`
- In `file:codeframe/git/workflow_manager.py`: When code is merged to main, update status to `BLUE`
- Each status change should call `entity_repository.update_entity_status()` and broadcast via WebSocket

### 5. Frontend Package Installation

**Add React Flow Dependency**

Update `file:web-ui/package.json`:

- Add `"reactflow": "^11.10.0"` to dependencies
- Add `"@reactflow/core": "^11.10.0"` and `"@reactflow/background": "^11.3.0"` for additional features
- Run `npm install` to install the new packages

### 6. Frontend Entity Diagram Component

**Create Entity Node Component**

Create `file:web-ui/src/components/entity-diagram/EntityNode.tsx`:

- Custom React Flow node component that displays entity name and status color
- Use color mapping: gray → `bg-gray-400`, red → `bg-red-500`, green → `bg-green-500`, purple → `bg-purple-500`, blue → `bg-blue-500`
- Display entity type as a badge (User, Task, Project, etc.)
- Add hover tooltip showing entity details and current status
- Make node clickable to show detail panel

**Create Entity Diagram Component**

Create `file:web-ui/src/components/entity-diagram/EntityDiagram.tsx`:

- Use React Flow's `<ReactFlow>` component with custom node types
- Fetch entity data from `/api/projects/{projectId}/entities` using SWR
- Transform API response into React Flow nodes and edges format
- Configure edge styles based on relationship type (solid for API, dashed for events, dotted for data)
- Add `<Background>` component for grid pattern
- Add `<Controls>` component for zoom/pan controls
- Implement auto-layout using React Flow's `useNodesState` and `useEdgesState` hooks
- Add deployment environment badge in top-right corner showing current env

**Create Entity Detail Panel**

Create `file:web-ui/src/components/entity-diagram/EntityDetailPanel.tsx`:

- Slide-out panel that appears when entity node is clicked
- Display entity name, type, current status, and status history
- Show list of related files and tests
- Show deployment status and environment
- Add "Close" button to dismiss panel

**Add WebSocket Real-time Updates**

Update `file:web-ui/src/lib/websocketMessageMapper.ts`:

- Add handlers for `entity_status_changed`, `entity_diagram_generated`, and `entity_deployed` message types
- Map WebSocket messages to state updates that trigger diagram re-render

### 7. Dashboard Tab Integration

**Add Entity Diagram Tab**

Update `file:web-ui/src/types/dashboard.ts`:

- Extend `DashboardTab` type to include `'entity-diagram'`

Update `file:web-ui/src/components/Dashboard.tsx`:

- Add new tab button in navigation section (line ~305) with label "Entity Diagram" and `data-testid="entity-diagram-tab"`
- Add tab panel section (after line ~694) that renders `<EntityDiagram projectId={projectId} />` when `activeTab === 'entity-diagram'`
- Only show tab when project phase is `PLANNING` or later (hide during discovery)
- Add conditional rendering: if no entities exist yet, show placeholder message "Entity diagram will appear after PRD generation"
- Wrap tab visibility in feature flag check to allow disabling tab if feature is not enabled

### 8. Type Definitions

**Create Entity Types**

Create `file:web-ui/src/types/entity.ts`:

- Define `EntityStatus` type: `'gray' | 'red' | 'green' | 'purple' | 'blue'`
- Define `DeploymentEnv` type: `'dev' | 'test' | 'staging' | 'production'`
- Define `RelationshipType` type: `'api' | 'data' | 'event' | 'import'`
- Define `Entity` interface with fields: `id`, `name`, `entity_type`, `status`, `deployment_env`, `created_at`, `updated_at`
- Define `EntityRelationship` interface with fields: `id`, `source_entity_id`, `target_entity_id`, `relationship_type`, `relationship_style`
- Define `EntityDiagramData` interface with fields: `entities: Entity[]`, `relationships: EntityRelationship[]`

### 9. API Client Integration

**Add Entity API Methods**

Update `file:web-ui/src/lib/api.ts`:

- Add `getEntities(projectId: number)` method that calls `GET /api/projects/{projectId}/entities`
- Add `updateEntityStatus(projectId: number, entityId: number, status: EntityStatus)` method
- Add `getEntityHistory(projectId: number, entityId: number)` method
- Export methods via `entitiesApi` object

### 10. Testing Considerations

**Backend Tests**

Create test files following existing patterns:

- `file:tests/persistence/test_entity_repository.py` - Test CRUD operations for entities and relationships
- `file:tests/planning/test_entity_extractor.py` - Test entity extraction from PRD text
- `file:tests/ui/test_entity_router.py` - Test API endpoints with authentication and authorization

**Frontend Tests**

Create test files following existing patterns:

- `file:web-ui/__tests__/components/entity-diagram/EntityDiagram.test.tsx` - Test diagram rendering and interactions
- `file:web-ui/__tests__/components/entity-diagram/EntityNode.test.tsx` - Test node component with different statuses
- `file:web-ui/__tests__/integration/entity-diagram-realtime-updates.test.tsx` - Test WebSocket updates

## Architecture Diagram

```mermaid
sequenceDiagram
    participant User
    participant Dashboard
    participant EntityDiagram
    participant WebSocket
    participant API
    participant LeadAgent
    participant EntityExtractor
    participant TestWorker
    participant Database

    User->>Dashboard: Navigate to Entity Diagram tab
    Dashboard->>EntityDiagram: Render component
    EntityDiagram->>API: GET /api/projects/{id}/entities
    API->>Database: Fetch entities & relationships
    Database-->>API: Return entity data
    API-->>EntityDiagram: EntityDiagramData
    EntityDiagram->>EntityDiagram: Transform to React Flow format
    EntityDiagram-->>User: Display diagram (all gray nodes)

    Note over LeadAgent,EntityExtractor: After PRD Generation
    LeadAgent->>EntityExtractor: extract_entities_from_prd(prd_text)
    EntityExtractor->>Database: Store entities (status=GRAY)
    EntityExtractor->>WebSocket: broadcast_entity_diagram_generated
    WebSocket-->>EntityDiagram: entity_diagram_generated event
    EntityDiagram->>EntityDiagram: Refresh diagram

    Note over TestWorker,Database: During TDD Red Phase
    TestWorker->>Database: Update entity status to RED
    TestWorker->>WebSocket: broadcast_entity_status_changed
    WebSocket-->>EntityDiagram: entity_status_changed event
    EntityDiagram->>EntityDiagram: Update node color to red

    Note over TestWorker,Database: During TDD Green Phase
    TestWorker->>Database: Update entity status to GREEN
    TestWorker->>WebSocket: broadcast_entity_status_changed
    WebSocket-->>EntityDiagram: entity_status_changed event
    EntityDiagram->>EntityDiagram: Update node color to green

    User->>EntityDiagram: Click entity node
    EntityDiagram->>EntityDetailPanel: Show detail panel
    EntityDetailPanel->>API: GET /api/projects/{id}/entities/{entityId}/history
    API->>Database: Fetch status history
    Database-->>API: Return history
    API-->>EntityDetailPanel: Status history data
    EntityDetailPanel-->>User: Display entity details
```

## Component Relationships

```mermaid
graph TD
    A[Dashboard.tsx] -->|activeTab='entity-diagram'| B[EntityDiagram.tsx]
    B -->|fetches data| C[API: /api/projects/id/entities]
    B -->|renders| D[EntityNode.tsx]
    B -->|listens to| E[WebSocket Client]
    D -->|onClick| F[EntityDetailPanel.tsx]
    F -->|fetches| G[API: /api/projects/id/entities/id/history]
    
    C -->|calls| H[entities.py router]
    H -->|uses| I[entity_repository.py]
    I -->|queries| J[Database: entities table]
    
    K[lead_agent.py] -->|after PRD| L[entity_extractor.py]
    L -->|stores| I
    L -->|broadcasts| M[websocket_broadcasts.py]
    
    N[test_worker_agent.py] -->|updates status| I
    N -->|broadcasts| M
    
    M -->|sends events| E
    
    style B fill:#e1f5ff
    style D fill:#e1f5ff
    style F fill:#e1f5ff
    style H fill:#fff4e1
    style I fill:#fff4e1
    style L fill:#fff4e1
```

## Data Flow Summary

| Phase | Trigger | Entity Status | Action |
|-------|---------|---------------|--------|
| Discovery Complete | PRD generated | GRAY | `entity_extractor` parses PRD, creates entities, broadcasts `entity_diagram_generated` |
| TDD Red | Tests created | RED | `test_worker_agent` updates status, broadcasts `entity_status_changed` |
| TDD Green | Tests pass | GREEN | `test_worker_agent` updates status, broadcasts `entity_status_changed` |
| Refactor | Review complete | PURPLE | `review_worker_agent` updates status, broadcasts `entity_status_changed` |
| Deployed | Merged to main | BLUE | `workflow_manager` updates status, broadcasts `entity_deployed` |

## File Creation Checklist

**Backend Files (Python)**
- `codeframe/persistence/migrations/migration_0XX_entity_tracking.py`
- `codeframe/persistence/repositories/entity_repository.py`
- `codeframe/planning/entity_extractor.py`
- `codeframe/ui/routers/entities.py`
- `codeframe/config/feature_flags.py` (add entity diagram feature flag)
- `tests/persistence/test_entity_repository.py`
- `tests/planning/test_entity_extractor.py`
- `tests/ui/test_entity_router.py`

**Frontend Files (TypeScript/React)**
- `web-ui/src/types/entity.ts`
- `web-ui/src/components/entity-diagram/EntityDiagram.tsx`
- `web-ui/src/components/entity-diagram/EntityNode.tsx`
- `web-ui/src/components/entity-diagram/EntityDetailPanel.tsx`
- `web-ui/src/lib/featureFlags.ts` (add entity diagram feature flag)
- `web-ui/__tests__/components/entity-diagram/EntityDiagram.test.tsx`
- `web-ui/__tests__/components/entity-diagram/EntityNode.test.tsx`
- `web-ui/__tests__/integration/entity-diagram-realtime-updates.test.tsx`

**Modified Files**
- `codeframe/core/models.py` (add Entity models and enums)
- `codeframe/ui/websocket_broadcasts.py` (add entity broadcast functions)
- `codeframe/agents/lead_agent.py` (integrate entity extraction)
- `codeframe/agents/test_worker_agent.py` (update entity status)
- `codeframe/agents/review_worker_agent.py` (update entity status)
- `codeframe/git/workflow_manager.py` (update entity status on merge)
- `web-ui/package.json` (add React Flow dependency)
- `web-ui/src/types/dashboard.ts` (add entity-diagram tab type)
- `web-ui/src/components/Dashboard.tsx` (add tab navigation and panel)
- `web-ui/src/lib/api.ts` (add entity API methods)
- `web-ui/src/lib/websocketMessageMapper.ts` (add entity event handlers)

---

Execution Information

Branch: main
Commit: 1260477

[frankbria]

Closing as part of v2 roadmap cleanup. This v1-specific issue is retained with the v1-legacy label as reference material for Phase 3 (Web UI rebuild). See the v2 strategic roadmap for current priorities.