High Priority: Fix multi-component version alignment

[tbrandenburg]

Problem

Frontend and backend share version 0.1.0 but have no compatibility enforcement, creating high risk of deployment mismatches:

• Risk of deploying incompatible frontend/backend versions
• No guidance for operators on compatible combinations
• Debugging issues becomes complex with version uncertainty
• Rolling updates may break system functionality

Evidence

• Both package.json and pyproject.toml declare version 0.1.0
• No version compatibility matrix
• No checks to prevent mismatched component deployment
• Docker compose deploys both services but versions aren't synchronized

Impact

High - Risk of production system breakage due to component version mismatches.

Recommended Solution

1. Synchronize major versions across components
2. Create compatibility matrix documentation
3. Implement compatibility checks at startup
4. Consider unified versioning strategy for the full stack

Acceptance Criteria

• Define version compatibility strategy (unified vs independent)
• Create version compatibility matrix documentation
• Implement startup version compatibility checks
• Update build process to enforce version alignment
• Add version mismatch detection to health checks
• Document deployment version requirements

Priority

High - Prevents production system failures from version mismatches

[github-actions]

Investigation: High Priority: Fix multi-component version alignment

Issue: #304 (#304)
Type: ENHANCEMENT
Investigated: 2026-03-15T00:00:00Z

Assessment

Metric	Value	Reasoning
Priority	HIGH	Prevents production failures from version mismatches, frequently requested
Complexity	MEDIUM	Requires changes across 3-4 files (backend, frontend, docker, docs) with API integration
Confidence	HIGH	Clear requirements, well-understood codebase patterns, standard approach

---

Problem Statement

Frontend and backend share version 0.1.0 but have no compatibility enforcement, creating high risk of deployment mismatches. The system lacks:

• Version information exposed via API
• Compatibility checks at startup
• Health check version reporting
• Documentation on compatible combinations

---

Analysis

Root Cause / Change Rationale

This is a missing feature (not a bug). The system currently has no version infrastructure:

1. Both package.json and pyproject.toml declare version 0.1.0 independently
2. No API endpoint exposes version information
3. Health check (/api/health) returns status but no version data
4. Frontend has no way to verify backend compatibility

Evidence Chain

Current state - Backend has no version endpoint:

• packages/pybackend/app.py:174-180 - Health check returns only status/workspace
• No version import or exposure anywhere in the codebase

Current state - Frontend has no version handling:

• packages/frontend/src/hooks/useApi.ts - No version API calls
• packages/frontend/package.json:3 - Version 0.1.0 declared but unused for compatibility

Current state - Docker builds have no version:

• docker/pybackend.Dockerfile - No version argument or label
• docker/frontend.Dockerfile - No version argument or label

Affected Files

File	Lines	Action	Description
packages/pybackend/app.py	174-180	UPDATE	Add version to health check endpoint
packages/pybackend/pyproject.toml	3	READ	Version already defined (0.1.0)
packages/frontend/src/hooks/useApi.ts	273-283	UPDATE	Add getVersion API call
packages/frontend/src/pages/DashboardPage.tsx	-	UPDATE	Display version mismatch warning
packages/frontend/package.json	3	READ	Version already defined (0.1.0)
docker/pybackend.Dockerfile	NEW	UPDATE	Add VERSION build arg
docker/frontend.Dockerfile	NEW	UPDATE	Add VERSION build arg
docker-compose.yml	NEW	UPDATE	Pass version to services
VERSION_COMPATIBILITY.md	NEW	CREATE	Document compatibility matrix

Integration Points

• Backend health endpoint at /api/health → extend with version
• Frontend calls /api/health on load → fetch and validate version
• Docker build passes version → containers know their version
• docker-compose orchestrates both → pass consistent version

Git History

• Not applicable - This is a new feature, not a regression
• No prior version handling exists in the codebase

---

Implementation Plan

Step 1: Add version to backend health endpoint

File: packages/pybackend/app.py
Lines: 174-180
Action: UPDATE

Current code:

@app.get("/api/health")
def health_check():
    return {
        "status": "ok",
        "workspace": str(get_workspace_home()),
        "made": str(get_made_directory()),
    }

Required change:

import tomllib

@app.get("/api/health")
def health_check():
    backend_version = "0.1.0"
    pyproject_path = Path(__file__).parent / "pyproject.toml"
    if pyproject_path.exists():
        try:
            with open(pyproject_path, "rb") as f:
                data = tomllib.load(f)
                backend_version = data.get("project", {}).get("version", "0.1.0")
        except Exception:
            pass
    
    return {
        "status": "ok",
        "version": backend_version,
        "workspace": str(get_workspace_home()),
        "made": str(get_made_directory()),
    }

Why: Exposes version to all API consumers including frontend

---

Step 2: Add version API to frontend

File: packages/frontend/src/hooks/useApi.ts
Lines: 273-285
Action: UPDATE

Current code (add after getDashboard):

getDashboard: () =>
  request<{
    projectCount: number;
    agentConnection: boolean;
    repositories: RepositorySummary[];
    madeHome: string;
    workspaceHome: string;
    madeDirectory: string;
    cronClock: CronClockSummary;
  }>("/dashboard"),

Required change:

getDashboard: () =>
  request<{
    projectCount: number;
    agentConnection: boolean;
    repositories: RepositorySummary[];
    madeHome: string;
    workspaceHome: string;
    madeDirectory: string;
    cronClock: CronClockSummary;
  }>("/dashboard"),
getVersion: () =>
  request<{ status: string; version: string }>("/health"),

Why: Frontend can fetch backend version for compatibility checking

---

Step 3: Add version mismatch warning to frontend

File: packages/frontend/src/pages/DashboardPage.tsx
Lines: Find where health check is called
Action: UPDATE

Add version validation after health check response:

const health = await api.getDashboard();
// Add version check
const { version: backendVersion } = await api.getVersion();
const frontendVersion = import.meta.env.VITE_APP_VERSION || "0.1.0";

if (backendVersion !== frontendVersion) {
  console.warn(`Version mismatch: frontend ${frontendVersion}, backend ${backendVersion}`);
  // Display warning in UI
}

Why: Alerts operators to version mismatches

---

Step 4: Update Dockerfiles to accept version

File: docker/pybackend.Dockerfile
Lines: 1-26
Action: UPDATE

Current code:

FROM python:3.12-slim
WORKDIR /app
...

Required change:

# syntax=docker/dockerfile:1
ARG VERSION=0.1.0
FROM python:3.12-slim

WORKDIR /app

LABEL version="${VERSION}"
ENV MADE_VERSION=${VERSION}
...

File: docker/frontend.Dockerfile
Lines: 1-23
Action: UPDATE

Current code:

FROM node:18-alpine AS build
...

Required change:

# syntax=docker/dockerfile:1
ARG VERSION=0.1.0
FROM node:18-alpine AS build

LABEL version="${VERSION}"
ENV VITE_APP_VERSION=${VERSION}
...

Why: Docker builds can inject version at build time

---

Step 5: Update docker-compose to pass version

File: docker-compose.yml
Lines: 5-24
Action: UPDATE

Required change:

services:
  pybackend:
    build:
      context: .
      dockerfile: docker/pybackend.Dockerfile
      args:
        VERSION: "0.1.0"
    environment:
      MADE_BACKEND_PORT: 3000

  frontend:
    build:
      context: .
      dockerfile: docker/frontend.Dockerfile
      args:
        VERSION: "0.1.0"
    depends_on:
      - pybackend

Why: Consistent version across services

---

Step 6: Create VERSION_COMPATIBILITY.md

File: VERSION_COMPATIBILITY.md
Action: CREATE

# MADE Version Compatibility

## Current Versions

| Component | Version |
|-----------|---------|
| Frontend  | 0.1.0   |
| Backend   | 0.1.0   |

## Compatibility Matrix

| Frontend | Backend | Compatible |
|----------|---------|------------|
| 0.1.x    | 0.1.x   | Yes        |
| 0.0.x    | any     | No         |
| any      | 0.0.x   | No         |

## Version Strategy

MADE uses **aligned major/minor versioning**:
- Frontend and backend share the same major.minor version
- Patch versions may differ within the same major.minor

## Version Checking

The backend exposes its version via `/api/health`:
```json
{
  "status": "ok",
  "version": "0.1.0",
  "workspace": "...",
  "made": "..."
}

Frontend checks backend version on startup and logs a warning if mismatch detected.

**Why**: Documents the compatibility strategy for operators

---

## Patterns to Follow

**From codebase - Backend endpoint pattern:**

```python
# SOURCE: packages/pybackend/app.py:174-180
@app.get("/api/health")
def health_check():
    return {
        "status": "ok",
        "workspace": str(get_workspace_home()),
        "made": str(get_made_directory()),
    }

From codebase - Frontend API pattern:

// SOURCE: packages/frontend/src/hooks/useApi.ts:273-283
getDashboard: () =>
  request<{...}>("/dashboard"),

---

Edge Cases & Risks

Risk/Edge Case	Mitigation
Frontend starts before backend	Frontend retries /health endpoint 3 times (already in place)
Version file missing	Fall back to "0.1.0" default
Network error during version check	Log warning but allow app to function (degraded)
Docker build without VERSION arg	Default to "0.1.0" in Dockerfile

---

Validation

Automated Checks

# Backend - Test health endpoint returns version
curl http://localhost:3000/api/health | jq '.version'

# Frontend - Test version display
npm run build:frontend
npm run preview:frontend
# Check console for version mismatch warning

# Docker - Test version injection
docker build --build-arg VERSION=1.0.0 -t made-frontend:test .
docker inspect made-frontend:test --format '{{index .Config.Labels "version"}}'

Manual Verification

1. Start backend: cd packages/pybackend && uv run uvicorn app:app --host 0.0.0.0 --port 3000
2. Verify health endpoint returns version: curl http://localhost:3000/api/health
3. Start frontend: npm run dev:frontend
4. Check browser console for version warning (if any)

---

Scope Boundaries

IN SCOPE:

• Version exposure via health endpoint
• Frontend version validation
• Docker build version injection
• Compatibility documentation

OUT OF SCOPE (do not touch):

• Automatic version updates
• Breaking change detection
• API version negotiation
• Complex compatibility matrix

---

Metadata

• Investigated by: GHAR
• Timestamp: 2026-03-15T00:00:00Z
• Artifact: .ghar/issues/issue-304.md