rdev/docs/ui/ideation/reference.md

Technical Reference: Foundary Studio UI

This document maps the Foundary Studio UI requirements to the existing rdev backend architecture and identifies necessary enhancements.

1. Architecture Overview

The UI acts as a control plane over the rdev API. It orchestrates three main domains:

1. Project Management: CRUD operations on K8s pods (claudebox).
2. SDLC Orchestration: Driving the feature lifecycle via agents.
3. Agent Interaction: Conversational interface for requirements gathering.

2. Feature Mapping

2.1 Project List & Dashboard

UI Requirement: "See a list of active projects... go into one project" Backend Support: GET /api/v1/projects

• Existing: Project domain model (internal/domain/project.go) supports ID, Name, Status (running, pending, etc.).
• Missing: Real-time status updates (SSE/WebSocket) for project health are implemented in internal/handlers/projects_stream.go but need UI integration.

2.2 Work Queue

UI Requirement: "See the list of work that is queued up" Backend Support: GET /api/v1/projects/{id}/work (inferred)

• Existing: WorkTask model (internal/domain/work.go) supports types build, test, deploy, sdlc.
• Logic: The WorkQueueStats and pagination are supported in the domain.
• UI Needs: A polling or SSE mechanism to update the task list as the orchestrator schedules work.

2.3 Conversational Request (The Architect)

UI Requirement: "Enter a flow where you can create a request... conversation creates specs" Backend Support: PARTIAL

• Existing: SDLCOrchestratorService (internal/service/sdlc_orchestrator.go) can execute agent actions.
• Missing:
  • Persistent Chat: No Chat or Message domain model exists to store history. AgentRequest has SessionID, but the backend doesn't seem to persist the conversation for UI retrieval.
  • Blueprint Model: The "Plan/Blueprint" (JSON structure of requirements) described in the vision is not yet a concrete backend entity.
• Proposal:
  • Create a Blueprint entity to store the structured plan (dataModel, endpoints, etc.).
  • Create a Conversation entity to store the chat history between User and Architect.

2.4 Request Review & Investigation

UI Requirement: "Request goes into a slot to be reviewed... problems investigated... questions raised" Backend Support: POST /projects/{id}/sdlc/execute

• Existing: The SDLCService and Classifier (implied) determine the next action (ActionBlocked, ActionTransition).
• Flow:
  1. UI sends execute request.
  2. Backend runs classification.
  3. If blocked/question needed, returns ActionBlocked or ActionIdle with a message.
  4. UI renders this as a "Question" or "Review Item".
  5. User responds via resolve endpoint (POST /projects/{id}/sdlc/resolve).

2.5 Execution & OTEL

UI Requirement: "Queues it up... see previous requests and full OTEL" Backend Support:

• Execution: SDLCOrchestratorService dispatches actions to agents (executeAgentAction).
• OTEL: internal/telemetry exists. The UI likely needs a proxy endpoint to query Trace/Metric data (e.g., via Jaeger/Prometheus API) or embed a view.

3. Data Model Enhancements (Required)

To support the vision, the backend likely needs these additions:

// Proposed Domain Models

type Blueprint struct {
    ID        string
    ProjectID string
    Sections  map[string]interface{} // JSON: DataModel, API, UI
    Status    string // Draft, Approved
}

type ChatMessage struct {
    ID        string
    ProjectID string
    Role      string // user, system (architect)
    Content   string
    Timestamp time.Time
}

4. API Integration Strategy

UI Feature	Endpoint	Notes
Project List	GET /projects	Polling or SSE for status changes.
Chat	POST /projects/{id}/chat	New Endpoint. Needs to persist msg & invoke Agent.
Plan View	GET /projects/{id}/blueprint	New Endpoint. Returns structured spec.
Build/Run	POST /projects/{id}/sdlc/execute	Triggers the actual work based on current state.
History	GET /projects/{id}/work	List of past WorkTasks.