Skip to content

ROADMAP.md

Latest commit

 

History

History
520 lines (393 loc) · 18.1 KB

ROADMAP.md

File metadata and controls

520 lines (393 loc) · 18.1 KB
Raw

Graph System Implementation Roadmap

Overall Progress

Current Status: Phase 3 Complete | Moving to Phase 4: Production Readiness

Phase Status Progress Story Points Completion
Phase 1 Complete 100% 101 / 101 Jan 2025
Phase 2 Complete 100% 39 / 39 Jan 2025
Phase 3 Complete 100% 47 / 47 Jan 2025
Phase 4 In Progress 0% 0 / 90 TBD
Total 75% Complete 187 / 277 68%

Test Coverage: 486 tests passing (9 new HD Wallet OTP scenarios)

Phase 1: API Testing Foundation (COMPLETE)

Goal: Establish comprehensive API test coverage for all core entities
Status: COMPLETE - All 31 user stories implemented
Completed: January 2025

SPEC0200: NodeTypes API Tests (21 SP)

  • #9 US01 - List NodeTypes (5 SP)
  • #10 US02 - Get NodeType by ID (3 SP)
  • #11 US03 - Create NodeType (3 SP)
  • #12 US04 - Update NodeType (3 SP)
  • #13 US05 - Delete NodeType (2 SP)
  • #14 US06 - Get Properties (2 SP)
  • #15 US07 - Get EdgeTypes (2 SP)

SPEC0201: EdgeTypes API Tests (20 SP)

  • #40 US01 - List EdgeTypes (5 SP)
  • #41 US02 - Get EdgeType by ID (3 SP)
  • #42 US03 - Create EdgeType (5 SP)
  • #43 US04 - Update EdgeType (3 SP)
  • #44 US05 - Delete EdgeType (2 SP)
  • #45 US06 - Get Properties (2 SP)

SPEC0202: Nodes API Tests (20 SP)

  • #46 US01 - List Nodes (5 SP)
  • #47 US02 - Get Node by ID (3 SP)
  • #48 US03 - Create Node (3 SP)
  • #49 US04 - Update Node (3 SP)
  • #50 US05 - Delete Node (2 SP)
  • #51 US06 - Get Children (2 SP)
  • #52 US07 - Get Properties (2 SP)

SPEC0203: Edges API Tests (20 SP)

  • #53 US01 - List Edges (5 SP)
  • #54 US02 - Get Edge by ID (3 SP)
  • #55 US03 - Create Edge (5 SP)
  • #56 US04 - Update Edge (3 SP)
  • #57 US05 - Delete Edge (2 SP)
  • #58 US06 - Get Properties (2 SP)

SPEC0204: Properties API Tests (20 SP)

  • #59 US01 - List Properties (5 SP)
  • #60 US02 - Get Property by ID (2 SP)
  • #61 US03 - Create Property (8 SP)
  • #62 US04 - Update Property (3 SP)
  • #63 US05 - Delete Property (2 SP)

Phase 1 Results: 101 SP completed, 31 user stories, 198+ test cases

Phase 2: Business Rules Engine (COMPLETE)

Goal: Implement declarative validation and calculation engine with NCalc integration
Status: COMPLETE - All 7 user stories implemented
Completed: January 2025

SPEC0205: RulesEngine (39 SP)

  • #73 US01 - Rule CRUD (3 SP)
  • #74 US02 - NCalc Evaluation (5 SP)
  • #75 US03 - Rule Type Validation (8 SP)
  • #64 US04 - Scope Evaluation (5 SP)
  • #65 US05 - Composite Trees (8 SP)
  • #76 US06 - Template Rendering (5 SP)
  • #77 US07 - API Integration (5 SP)

Phase 2 Results: 39 SP completed, 7 user stories, 129+ test cases

Phase 3: AI & RAG Integration (COMPLETE)

Goal: Implement vector embeddings, RAG system, and multi-agent routing
Status: COMPLETE - All 8 user stories implemented
Completed: January 2025

SPEC0206: PropertyVector & Multi-Agent RAG (47 SP)

  • #78 US01 - PropertyVector Entity (3 SP)
  • #79 US02 - Embedding Providers (5 SP)
  • #80 US03 - Language Model Providers (5 SP)
  • #81 US04 - Agent Router (8 SP)
  • #82 US05 - Property Embedding (5 SP)
  • #83 US06 - Vector Search (5 SP)
  • #84 US07 - Code Generation (Qwen) (8 SP)
  • #85 US08 - API Integration (8 SP)

Phase 3 Results: 47 SP completed, 8 user stories, 138+ test cases

Phase 4: Production Readiness (IN PROGRESS)

Goal: Prepare system for production deployment with database migrations, CI/CD, authentication, and documentation
Status: IN PROGRESS - 0% complete
Estimated: 85 SP, ~8-10 weeks

SPEC0207: Production Readiness (85 SP)

Database Migrations (10 SP)

  • SPEC0207.US01 - PostgreSQL migration library (10 SP)
    • Create migration project
    • Add Npgsql.EntityFrameworkCore.PostgreSQL
    • Add Pgvector.EntityFrameworkCore
    • Create initial migration
    • Configure pgvector extension
    • Add migration scripts
    • Documentation

Note: SQLite and SQL Server providers were removed to keep pgvector-only support.

Infrastructure & DevOps (20 SP)

  • SPEC0207.US04 - Docker CI/CD pipeline (20 SP)
    • Create Dockerfile for API
    • Setup multi-stage build
    • Create docker-compose.yml
    • Configure GitHub Actions workflow
    • Setup container registry
    • Add automated versioning
    • Configure security scanning
    • Add health checks
    • Multi-architecture support
    • Documentation

Security & Authentication (30 SP)

  • SPEC0207.US05 - Authentication & Authorization (25 SP)

    • Add ASP.NET Core Identity
    • Create ApplicationUser entity
    • Configure Identity DbContext
    • Implement signup endpoint
    • Implement signin endpoint
    • Configure JWT tokens
    • Add refresh token support
    • Implement role-based authorization
    • Add [Authorize] attributes
    • Implement email confirmation
    • Implement password reset
    • Configure email service
    • Add 2FA support
    • Security testing
    • Documentation

  • #99 Replace IdentityGraphContext with graph-native identity storage

    • Model users/roles/claims/logins/tokens in graph nodes/edges/properties
    • Implement graph-backed identity store layer
    • Remove ASP.NET Identity EF tables from API runtime
    • Keep auth behavior stable and tests green

  • SPEC0207.US03 - HD Wallet OTP Tests (5 SP)

    • Create 9 scenario test files
    • Test OTP generation
    • Test OTP login
    • Test time-based derivation
    • Test 2FA enable/disable
    • Fix API routes in tests
    • Implement missing endpoints

  • Implement HD Wallet OTP Endpoints (5 SP) (issue #98 closed)

    • Add session/cache infrastructure
    • Implement GenerateOTPAsync
    • Implement LoginWithOTPAsync
    • Update authentication flow
    • Test OTP authentication
    • Documentation

Demo Applications (10 SP)

  • SPEC0207.US06 - TODO demo application (10 SP) (superseded by #97)

  • SPEC0207.US07 - Generate RAG demo data (5 SP)

    • Create synthetic codebase data
    • Generate technical documentation
    • Add architecture examples
    • Create diverse graph structures
    • Generate vector embeddings
    • Build data seeder service
    • Add command-line tool
    • Documentation

Documentation (10 SP)

  • #91 Update README (5 SP)

    • Update project overview
    • Add badges (build, coverage, version)
    • Document features
    • Add getting started guide
    • Document API usage
    • Add deployment guide
    • Link to examples
    • Update roadmap reference

  • #94 Roadmap improvements (5 SP)

    • Add completion percentages
    • Update with Phase 4 items
    • Add metrics tracking
    • Include "Recently Completed" section
    • Add "Up Next" priorities
    • Document decision rationale

Phase 4 Target: 90 SP, Production-ready system with migrations, CI/CD, auth, demos, and documentation

Progress Metrics

Completed Work

  • Total Story Points: 187 / 277 (68%)
  • Total User Stories: 46 / 54 (85%)
  • Total Test Cases: 486+ passing
  • Code Coverage: Comprehensive integration tests

Recently Completed (January 2025)

  • SPEC0202: Fixed integration tests with FakeGraphContextFactory pattern
  • Issues #46-#52 closed (Nodes API)
  • Fixed WebApplicationFactory test database configuration
  • All 444 tests passing
  • Closed issues #95, #98, #93, #91, #88

Up Next

  • PostgreSQL migration library (#94)
  • Docker CI/CD setup (#89)
  • Authentication: Email confirmation & password reset (issue TBD)

SPEC0208: UserContext (TBD)

Goal: Define long-lived, user-scoped reasoning state (UserState) and a structured agent loop that builds it from WorkItem source-of-truth nodes.

  • #95 SPEC0208 - UserState + Agent Loop (GraphContext)
    • Define UserState core types and reducer
    • Define tool-using agent loop contract
    • Specify user stories for UserContext epic

SPEC0209: GraphSession (TBD)

Goal: Replace ASP.NET Identity with graph-native session binding for UI/CLI/MCP/API clients.

  • #96 SPEC0209 - GraphSession + GraphSessionClient
    • Define GraphSession server responsibilities
    • Define GraphSessionClient model binding and caching
    • Specify schema mapping rules for node/edge properties

SPEC0210: Samples App (WASM) (TBD)

Goal: Build a Razor WebAssembly samples app in samples/app to demo SPEC0200-0209 features.

  • #97 SPEC0210 - Samples App (WASM) for SPEC0200-0209
    • Define app navigation by SPEC
    • Implement demo pages for each SPEC
    • Add mock/live data switch per feature

Icebox / Future Ideas

  • Performance optimization and benchmarking
  • Advanced graph algorithms (shortest path, centrality)
  • GraphQL API layer
  • Real-time subscriptions with SignalR
  • Audit logging and change tracking
  • Multi-tenancy with tenant isolation
  • Advanced caching strategies

Parallel Work Opportunities

While following the sequential phase approach is safest, some work can be parallelized:

Team Split Option 1: Two Streams

Stream A: API Testing (1 developer)

  • SPEC0200-0204 (Weeks 1-12)
  • Can work independently
  • Validates existing APIs

Stream B: RulesEngine (1-2 developers)

  • SPEC0205 (Weeks 5-12, starts after SPEC0204.US03)
  • Needs Property CRUD APIs working
  • Can start once Property create/update tested

Team Split Option 2: Three Streams

Stream A: API Testing (1 developer)

  • SPEC0200-0204 continuously

Stream B: RulesEngine (1 developer)

  • SPEC0205 (starts Week 5)

Stream C: RAG Infrastructure (1 developer)

  • SPEC0206.US01-US02 (starts Week 10)
  • Can prepare infrastructure while RulesEngine completes

External Dependencies

Prerequisites by Phase

Phase 1: API Testing

  • .NET 10 SDK
  • xUnit test framework
  • EF Core In-Memory provider (for tests)
  • Existing API controllers

Phase 2: RulesEngine

  • NCalcAsync NuGet package
  • ExecutionContext (already exists)
  • Property entity CRUD APIs

Phase 3: RAG & AI

  • PostgreSQL with pgvector extension
  • Npgsql.EntityFrameworkCore.PostgreSQL
  • Pgvector.EntityFrameworkCore
  • LM Studio (local dev) or Ollama (production)
  • Models downloaded:
  • nomic-embed-text-v1.5-GGUF (Q8_0)
  • qwen3-coder-38b-instruct
  • llama-3.2-3b-instruct

Infrastructure Setup Timeline

Week Setup Task Owner Status
1 Install .NET 10 SDK + xUnit Dev Team Done
13 Install NCalcAsync package Backend Dev Pending
18 Setup PostgreSQL + pgvector DevOps Pending
18 Install LM Studio + download models AI Dev Pending
21 Setup Ollama (production) DevOps Pending

Milestones & Success Criteria

Milestone 1: API Foundation (Week 12)

Criteria:

  • All 31 API user stories implemented
  • 198 UACs passing (100% green)
  • Test coverage > 80% on controllers
  • CI/CD running all tests successfully
  • API documentation auto-generated

Deliverable: Tested, documented API layer ready for advanced features

Milestone 2: Business Rules (Week 17)

Criteria:

  • RulesEngine operational with all 12 RuleTypes
  • 129 UACs passing
  • Composite rule trees working (AND/OR/NOT)
  • Template system integrated with ExecutionContext
  • NCalc expressions evaluating correctly
  • Rules API endpoints functional

Deliverable: Declarative validation system enabling runtime rule changes

Milestone 3: AI-Powered System (Week 23)

Criteria:

  • PropertyVector embeddings generating automatically
  • 138 UACs passing
  • Vector similarity search < 50ms (100k vectors)
  • Agent router correctly detecting query types (>95% accuracy)
  • Qwen generating compilable C# code (>90% first-try)
  • RAG context improving agent responses
  • LM Studio/Ollama auto-loading models

Deliverable: Production-ready AI-powered graph system with code generation

Metrics & KPIs

Development Velocity

  • Target: 8-10 story points per week per developer
  • Phase 1: 101 SP / 10 weeks = ~10 SP/week (1 dev)
  • Phase 2: 39 SP / 5 weeks = ~8 SP/week (1 dev)
  • Phase 3: 47 SP / 6 weeks = ~8 SP/week (1 dev)

Quality Metrics

  • Test Coverage: > 80% for all new code
  • UAC Pass Rate: 100% (all scenarios passing)
  • Build Success: > 95% (CI/CD green)
  • Code Review: < 24 hours turnaround

Performance Metrics (Phase 3)

  • Embedding Generation: < 100ms per property
  • Vector Search: < 50ms for top-10 results
  • Agent Query: < 5s for code generation, < 2s for reasoning

Risk Management

Risk Impact Mitigation
API tests reveal bugs High Fix bugs before Phase 2; builds quality foundation
NCalc expressions too complex Medium Start with simple validators, iterate
pgvector performance issues Medium Implement indexing early, test with realistic data
LM Studio model loading slow Low Expected, document auto-loading behavior
Qwen code quality varies Medium Implement quality checks, iterate on prompts
Scope creep High Strict adherence to feature files, UACs as contract

Documentation Deliverables

By Milestone

Milestone 1 Docs:

  • API test coverage report
  • API endpoint documentation (Swagger)
  • Testing framework guide updates

Milestone 2 Docs:

  • RulesEngine user guide
  • Rule expression syntax reference
  • Template system documentation
  • Migration guide (PropertyKey to PropertyId)

Milestone 3 Docs:

  • RAG system architecture
  • Agent routing guide
  • Model management guide (LM Studio/Ollama)
  • Qwen code generation examples
  • Performance tuning guide

Quick Wins

Tasks that deliver value early:

Week 2: First API Tests Green

  • SPEC0200.US01 (List NodeTypes)
  • Validates test infrastructure
  • Builds team confidence

Week 5: First Rule Working

  • SPEC0205.US01 + US02 (Rule CRUD + NCalc)
  • Demonstrates declarative validation
  • Stakeholder demo-able

Week 19: First Embedding Generated

  • SPEC0206.US01 + US02 (PropertyVector + Embedding)
  • Shows AI integration working
  • Visual similarity search demo

Reference Links

Specifications

GitHub Issues

Testing Framework

Gantt Chart (High-Level)

Week    Phase 1: API Testing       Phase 2: Rules    Phase 3: RAG & AI
1-4     (SPEC0200-0201)
5-8     (SPEC0202-0203)
9-12    (SPEC0204)
13-14                              (US01-02)
15-16                              (US03)
17                                 (US04-07)
18-19                                                (US01-02,06)
20-21                                                (US03,05)
22-23                                                (US04,07-08)

Last Updated: 2025-01-28
Total Effort: 187 Story Points
Estimated Duration: 19-23 weeks (4.75-5.75 months)
Team Size: 1-3 developers
Status: Phase 4 In Progress