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

```go
// 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 `WorkTask`s. |