Backend Integration Guide

Overview

Coditect V5 backend is a Rust/Actix-web API with JWT authentication and FoundationDB persistence.

Architecture

┌─────────────────┐
│  React Frontend │  (Port 5173)
│   (Vite Dev)    │
└────────┬────────┘
         │ HTTP/REST
         ▼
┌─────────────────┐
│   Backend API   │  (Port 8080)
│  (Actix-web)    │
└────────┬────────┘
         │ FDB Protocol
         ▼
┌─────────────────┐
│ FoundationDB    │  (Port 4500)
│    Cluster      │
└─────────────────┘

API Endpoints

Base URL

• Development: http://localhost:8080/api/v5
• Production: https://api.coditect.ai/api/v5

Configure in .env:

VITE_API_URL=http://localhost:8080/api

Authentication

POST /v5/auth/register

{
  "email": "user@example.com",
  "password": "securepassword",
  "firstName": "John",
  "lastName": "Doe",
  "company": "ACME Corp"  // optional
}

Response:

{
  "success": true,
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "user@example.com",
      "name": "John Doe",
      "firstName": "John",
      "lastName": "Doe",
      "role": "owner",
      "company": "ACME Corp"
    }
  }
}

POST /v5/auth/login

{
  "email": "user@example.com",
  "password": "securepassword"
}

Response: Same as register

POST /v5/auth/logout

• Headers: Authorization: Bearer <token>
• Response: { "success": true, "data": { "message": "Logged out successfully" } }

Session Management (Protected)

All session endpoints require JWT token in header:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

POST /v5/sessions

{
  "name": "My Project",
  "workspacePath": "/workspace/projects/my-project"  // optional
}

GET /v5/sessions

• Returns array of sessions for current tenant

GET /v5/sessions/{sessionId}

• Returns single session by ID

DELETE /v5/sessions/{sessionId}

• Deletes session (must belong to user's tenant)

Frontend Integration

Auth Store (Zustand)

Located at src/stores/auth-store.ts

Updated for V5:

• Login endpoint: /v5/auth/login
• Register endpoint: /v5/auth/register

Demo Mode (for development):

• Email: demo@coditect.ai
• Password: demo
• Bypasses backend API

API Client Pattern

const apiUrl = (path: string): string => {
  const baseUrl = import.meta.env.VITE_API_URL || 'https://api.coditect.ai'
  return `${baseUrl}${path}`
}

// Usage
const response = await fetch(apiUrl('/v5/sessions'), {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
})

Running Locally

With Docker Compose (Recommended)

cd backend
cp .env.example .env
# Edit .env if needed
docker-compose up -d

Services:

• API: http://localhost:8080
• FoundationDB: localhost:4500

Without Docker (Manual)

1. Install FoundationDB 7.1:

   curl -LO https://github.com/apple/foundationdb/releases/download/7.1.27/foundationdb-clients_7.1.27-1_amd64.deb
   sudo dpkg -i foundationdb-clients_7.1.27-1_amd64.deb

2. Install Rust:

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

3. Build and run:

   cd backend
   cargo build --release
   JWT_SECRET=dev-secret ./target/release/api-server

Database Schema

Key Patterns

users/{user_id}                          → User record (JSON)
users/by_email/{email}                   → user_id (UUID bytes)
users/{user_id}/tenants/{tenant_id}      → UserTenant association

tenants/{tenant_id}                      → Tenant record (JSON)
tenants/{tenant_id}/sessions/{session_id} → session_id (UUID bytes)

sessions/{session_id}                    → Session record (JSON)

Multi-Tenancy

• Every user has a self-tenant (UUID v5 from user_id)
• JWT tokens include tenant_id for isolation
• All sessions are scoped to tenant
• Future: Support organization tenants

Security

JWT Tokens

• Algorithm: HS256
• Secret: Configured via JWT_SECRET env var
• Expiration: 24 hours
• Claims:
  • sub: user_id
  • tenant_id: tenant_id
  • email: user email
  • exp: expiration timestamp
  • iat: issued at timestamp

Password Hashing

• Algorithm: Argon2id (default parameters)
• Salt: Generated per-password with SaltString
• Hash format: PHC string format

CORS

Configured to allow all origins in development. For production:

let cors = Cors::default()
    .allowed_origin("https://coditect.ai")
    .allowed_methods(vec!["GET", "POST", "PUT", "DELETE"])
    .allowed_headers(vec![header::AUTHORIZATION, header::CONTENT_TYPE])
    .max_age(3600);

Environment Variables

Backend (.env)

# Server
HOST=0.0.0.0
PORT=8080

# JWT
JWT_SECRET=your-secret-key-change-in-production

# FoundationDB
FDB_CLUSTER_FILE=/etc/foundationdb/fdb.cluster

# Logging
RUST_LOG=info

Frontend (.env)

VITE_API_URL=http://localhost:8080/api

Testing

Manual API Testing

Register:

curl -X POST http://localhost:8080/api/v5/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"password123","firstName":"Test","lastName":"User"}'

Login:

curl -X POST http://localhost:8080/api/v5/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"password123"}'

Create Session (replace TOKEN):

curl -X POST http://localhost:8080/api/v5/sessions \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Session","workspacePath":"/workspace/test"}'

Integration Testing

1. Start backend: cd backend && docker-compose up -d
2. Start frontend: npm run dev
3. Open browser: http://localhost:5173
4. Test registration and login flows

Deployment

GCP Cloud Run

See backend/Dockerfile for container image.

Required environment variables:

• JWT_SECRET (from Secret Manager)
• FDB_CLUSTER_FILE path
• PORT (injected by Cloud Run)

FoundationDB cluster should be deployed separately (GKE recommended).

Troubleshooting

Frontend can't connect to backend

1. Check backend is running: curl http://localhost:8080/api/v5/health
2. Check CORS headers in browser DevTools
3. Verify VITE_API_URL in frontend .env

JWT validation failing

1. Verify JWT_SECRET matches between frontend and backend
2. Check token expiration (24 hours)
3. Inspect token claims at https://jwt.io

FoundationDB connection errors

1. Check FDB cluster file exists: cat /etc/foundationdb/fdb.cluster
2. Test connection: fdbcli (if FDB tools installed)
3. Check Docker network if using docker-compose

Next Steps

1. Add profile update endpoint
2. Add avatar upload support
3. Implement session workspace file operations
4. Add MCP integration for llm access
5. Add A2A endpoints for agent coordination