Planning stage 3.1
This commit is contained in:
parent
7f34cc78ee
commit
581cb768ba
1 changed files with 180 additions and 1 deletions
|
|
@ -6,4 +6,183 @@
|
|||
- Use typescript
|
||||
- Rely on client generated from protobuf interface definitions
|
||||
|
||||
TODO
|
||||
## Minimal Design
|
||||
|
||||
### Architecture
|
||||
|
||||
Single-page application consuming Build Graph Service HTTP endpoints with real-time updates via polling.
|
||||
|
||||
```
|
||||
┌─────────────────┐ HTTP API ┌─────────────────┐
|
||||
│ Dashboard SPA │ ◄────────────► │ Build Graph │
|
||||
│ (Mithril/TS) │ │ Service │
|
||||
└─────────────────┘ └─────────────────┘
|
||||
│
|
||||
│
|
||||
┌─────────────────┐
|
||||
│ Build Event Log │
|
||||
│ (SQLite/PG) │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
### Core Pages
|
||||
|
||||
#### 1. Build Request Status (`/builds/{id}`)
|
||||
Primary operational page showing real-time build progress.
|
||||
|
||||
**UI Elements:**
|
||||
- Build request header (ID, status, timestamp)
|
||||
- Job/Partition status directed graph (with status requested → scheduled → building → available/failed)
|
||||
- Per-job execution timeline with logs from build events
|
||||
- Delegation indicators (when partitions delegated to other builds)
|
||||
|
||||
**Key Features:**
|
||||
- Auto-refresh every 2 seconds when tab is active and build is running
|
||||
- Expandable job details with execution logs from build event log
|
||||
- Visual progress indication via graph
|
||||
|
||||
#### 2. Partitions List Page (`/partitions`)
|
||||
Lists recently built partitions (searchable), with a "Build" button to trigger a new partition build (or go to existing).
|
||||
|
||||
#### 3. Partition Status (`/partitions/{base64_ref}`)
|
||||
Shows partition lifecycle and build history.
|
||||
|
||||
**UI Elements:**
|
||||
- Partition info (ref, current status, last updated)
|
||||
- Build history table (build requests that produced this partition)
|
||||
- "Build Now" button with force option
|
||||
- Related partitions (upstream/downstream dependencies)
|
||||
|
||||
**URL Handling:**
|
||||
- Partition refs base64-encoded in URLs to avoid parsing ambiguity
|
||||
- Client-side encode/decode for partition references
|
||||
|
||||
#### 4. Recent Activity (`/`)
|
||||
Dashboard home showing system activity.
|
||||
|
||||
**UI Elements:**
|
||||
- Recent build requests (fetched from service)
|
||||
- Active builds count
|
||||
- Recent partition builds
|
||||
- System health indicators
|
||||
|
||||
**Stateless Design:**
|
||||
- All data fetched from Build Graph Service on page load
|
||||
- No client-side caching or state persistence
|
||||
|
||||
#### 5. Jobs List Page (`/jobs`)
|
||||
Lists jobs in graph with high level metedata per job and a link to each.
|
||||
|
||||
#### 6. Job Metrics (`/jobs/{label}`)
|
||||
Job performance and reliability metrics. (with job label base64 encoded)
|
||||
|
||||
**UI Elements:**
|
||||
- Success rate chart (data from build event log via service)
|
||||
- Average duration trends
|
||||
- Recent runs table (with requested partitions)
|
||||
|
||||
#### 5. Graph Analysis (`/analyze`)
|
||||
Interactive build graph visualization.
|
||||
|
||||
**UI Elements:**
|
||||
- Partition input form
|
||||
- Generated job graph (mermaid.js rendering - simple visualization)
|
||||
- Execution plan table
|
||||
|
||||
### Technical Implementation
|
||||
|
||||
#### State Management
|
||||
```typescript
|
||||
// Minimal stateless approach - only UI state
|
||||
interface AppState {
|
||||
currentPage: string;
|
||||
polling: {
|
||||
active: boolean;
|
||||
interval: number;
|
||||
tabVisible: boolean; // Page Visibility API
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
#### API Client
|
||||
```typescript
|
||||
class BuildGraphClient {
|
||||
async getBuildStatus(id: string): Promise<BuildStatus>;
|
||||
async getPartitionStatus(ref: string): Promise<PartitionStatus>;
|
||||
async submitBuild(partitions: string[]): Promise<string>;
|
||||
async getJobMetrics(label: string): Promise<JobMetrics>;
|
||||
async analyzeBuild(partitions: string[]): Promise<JobGraph>;
|
||||
async getRecentActivity(): Promise<ActivitySummary>;
|
||||
}
|
||||
|
||||
// Partition reference utilities
|
||||
function encodePartitionRef(ref: string): string {
|
||||
return btoa(ref).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
|
||||
}
|
||||
|
||||
function decodePartitionRef(encoded: string): string {
|
||||
return atob(encoded.replace(/-/g, '+').replace(/_/g, '/'));
|
||||
}
|
||||
```
|
||||
|
||||
#### Routing
|
||||
```typescript
|
||||
const routes: RouteDef[] = [
|
||||
{ path: '/', component: RecentActivity },
|
||||
{ path: '/builds/:id', component: BuildStatus },
|
||||
{ path: '/partitions/:base64_ref', component: PartitionStatus },
|
||||
{ path: '/jobs/:label', component: JobMetrics },
|
||||
{ path: '/analyze', component: GraphAnalysis }
|
||||
];
|
||||
```
|
||||
|
||||
### Styling Approach
|
||||
|
||||
Minimal CSS with utility classes:
|
||||
- CSS Grid for layouts
|
||||
- Tailwind + daisyui
|
||||
- Consistent spacing scale (4px base unit)
|
||||
- Monospace font for partition refs/IDs
|
||||
- Color coding for status indicators
|
||||
|
||||
### Real-time Updates
|
||||
|
||||
Polling-based updates with Page Visibility API integration:
|
||||
- 2s interval when tab is active and build is running
|
||||
- 10s interval when tab is active and build is completed
|
||||
- Polling stops when tab is not visible
|
||||
- Manual refresh button always available
|
||||
- Uses `document.visibilityState` to detect tab focus
|
||||
|
||||
### Bundle Size Targets
|
||||
|
||||
- Initial bundle: < 50KB gzipped
|
||||
- Mithril: ~10KB
|
||||
- Custom code: ~20KB
|
||||
- CSS: ~5KB
|
||||
- Protobuf client: ~15KB
|
||||
|
||||
### Data Flow
|
||||
|
||||
All data flows from Build Graph Service:
|
||||
1. **Job Logs**: Stored in build event log, retrieved via service API
|
||||
2. **Partition Status**: Computed from build events by service
|
||||
3. **Build History**: Maintained in build event log
|
||||
4. **Metrics**: Aggregated from build events by service
|
||||
5. **No Client State**: Dashboard fetches fresh data on each page load
|
||||
|
||||
### Development Workflow
|
||||
|
||||
```bash
|
||||
# Development server
|
||||
npm run dev
|
||||
|
||||
# Build for production
|
||||
npm run build
|
||||
|
||||
# Type checking
|
||||
npm run typecheck
|
||||
|
||||
# Bundled with build graph service
|
||||
./scripts/build_dashboard
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in a new issue