a69eb7e587
Implements all 5 phases of Foundary Studio backend:
Phase 1: Chat Persistence (8 API endpoints)
- Conversations and messages with proper cascading deletes
- PostgreSQL schema with auto-update triggers
- Full CRUD operations with structured logging
Phase 2: Blueprint Entity (5 API endpoints)
- JSONB spec storage with GIN indexes
- Flexible structured data for project specifications
- Version-controlled blueprint management
Phase 3: Architect Service (3 API endpoints)
- Conversational AI orchestration with Claude
- Multi-turn dialogue with context building
- Blueprint spec extraction from conversations
Phase 4: Work Queue Integration
- Verified existing endpoint compatibility
Phase 5: Structured Questions (6 API endpoints)
- Four question types: text, choice, multichoice, yesno
- Answer validation with proper constraints
- Conversation-linked Q&A flow
Architecture:
- Textbook hexagonal architecture (domain → port → adapter → service → handler)
- Zero external dependencies in domain layer
- Consistent error handling with proper wrapping
- Auth scopes on all routes (projects:read, projects:execute)
- Structured logging with operation context and duration tracking
- NULL-safe DTO converters throughout
Database:
- 3 new migrations (019, 020, 021)
- UUIDs for all primary keys
- Proper foreign key constraints with ON DELETE CASCADE
- Optimized indexes including partial index for unanswered questions
- Auto-update triggers for timestamps
OpenAPI Documentation:
- Complete API documentation under 'Foundary' tag
- 22 new endpoints documented with examples
- Request/response schemas for all operations
Logging Improvements:
- Added operation field to all service logs
- Added duration_ms tracking for performance monitoring
- Log response_length instead of full response content
- Consistent use of logging field constants
- Execute-then-log pattern for delete operations
Files: 32 changed, 2800+ lines added
- 7 domain models
- 3 database migrations
- 3 port interfaces
- 3 postgres adapters
- 4 services (conversation, blueprint, question, architect)
- 4 handlers with DTOs
- OpenAPI documentation
- Integration in main.go
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
87 lines
4.2 KiB
Markdown
87 lines
4.2 KiB
Markdown
# 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. |
|