Skip to main content

Backend API - Phase 2/3 Complete ✅

What Was Built​

Rust/Actix-web backend API with:

  • ✅ JWT authentication (Argon2 password hashing)
  • ✅ User registration and login endpoints
  • ✅ Session management (CRUD operations)
  • ✅ FoundationDB integration
  • ✅ Multi-tenant architecture (self-tenants)
  • ✅ CORS support
  • ✅ Health check endpoints
  • ✅ Docker configuration
  • ✅ Google Cloud Build deployment

File Structure​

backend/
├── src/
│   ├── main.rs                  # Entry point, HTTP server setup
│   ├── state.rs                 # App state (database connection)
│   ├── db/
│   │   ├── mod.rs              # FDB initialization
│   │   ├── models.rs           # User, Tenant, Session models
│   │   └── repositories.rs     # Database operations
│   ├── handlers/
│   │   ├── mod.rs
│   │   ├── health.rs           # /health, /ready endpoints
│   │   ├── auth.rs             # /auth/register, /auth/login, /auth/logout
│   │   └── sessions.rs         # Session CRUD
│   ├── middleware/
│   │   ├── mod.rs
│   │   ├── auth.rs             # JWT middleware
│   │   └── auth_json.rs        # JSON error responses
│   ├── models/
│   │   ├── mod.rs
│   │   └── response.rs         # ApiResponse wrapper
│   └── services/
│       └── mod.rs              # Placeholder for future services
├── cargo.toml                   # Rust dependencies
├── Dockerfile                   # Multi-stage Docker build
├── docker-compose.yml           # Local dev with FDB
├── cloudbuild.yaml             # GCP Cloud Build config
├── .env.example                # Environment template
├── .gitignore
└── README.md                   # Backend docs

API Endpoints​

Base URL​

  • Dev: http://localhost:8080/api/v5
  • Prod: https://api.coditect.ai/api/v5

Public Endpoints​

Health:

  • GET /v5/health → {"success": true, "data": {"status": "healthy"}}
  • GET /v5/ready → {"success": true, "data": {"status": "ready"}}

Authentication:

  • POST /v5/auth/register → Register new user, returns JWT token
  • POST /v5/auth/login → Login, returns JWT token
  • POST /v5/auth/logout → Client-side logout

Protected Endpoints (JWT required)​

Sessions:

  • POST /v5/sessions → Create new session
  • GET /v5/sessions → List user's sessions
  • GET /v5/sessions/{id} → Get session by ID
  • DELETE /v5/sessions/{id} → Delete session

Database Schema (FoundationDB)​

users/{user_id}                          → User{id, email, password_hash, ...}
users/by_email/{email}                   → user_id (UUID bytes)
users/{user_id}/tenants/{tenant_id}      → UserTenant{role, company, ...}

tenants/{tenant_id}                      → Tenant{id, name, type}
tenants/{tenant_id}/sessions/{session_id}→ session_id (UUID bytes)

sessions/{session_id}                    → Session{id, name, workspace_path, ...}

Multi-Tenancy​

  • Every user gets a self-tenant on registration (UUID v5 deterministic)
  • JWT tokens include tenant_id for isolation
  • All sessions are scoped to tenant
  • Future: Organization tenants for team collaboration

Security​

JWT Tokens:

  • Algorithm: HS256
  • Secret: JWT_SECRET env var
  • Expiration: 24 hours
  • Claims: sub (user_id), tenant_id, email, exp, iat

Passwords:

  • Hashed with Argon2id (default parameters)
  • Unique salt per password
  • PHC string format

CORS:

  • Allows all origins (dev)
  • Configurable for production

Frontend Integration​

Updated src/stores/auth-store.ts:

  • Changed login endpoint: /v2/auth/login → /v5/auth/login
  • Changed register endpoint: /v2/auth/register → /v5/auth/register
  • Demo mode still works (demo@coditect.ai / demo)

API Base URL:

  • Configured via VITE_API_URL environment variable
  • Defaults to https://api.coditect.ai if not set

Running Locally​

cd backend
docker-compose up -d

Services:

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

Manual (Requires Rust + FDB installed)​

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

Deployment​

Google Cloud Build​

Automated build and deploy on push to main branch:

  1. Build: Multi-stage Rust Docker image
  2. Push: Artifact Registry (us-central1-docker.pkg.dev)
  3. Deploy: Cloud Run (coditect-v5-api)

Configuration: See backend/cloudbuild.yaml

Secrets: JWT_SECRET from Secret Manager

Network: VPC Connector to FoundationDB on GKE

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 Project","workspacePath":"/workspace/test"}'

Integration Testing​

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

Next Steps (Phase 3+)​

  1. File Operations (/sessions/{id}/files)

    • List workspace files
    • Read/write file content
    • Create/delete/rename files

  2. MCP Integration (/mcp)

    • LM Studio tool calls
    • Resource access
    • Prompt templates

  3. A2A Integration (/a2a)

    • Agent coordination
    • Inter-agent messaging
    • Task delegation

  4. Agent Management (/agents)

    • Create/configure agents
    • Assign to sessions
    • Execution tracking

  5. Profile Management (/users/me)

    • Update profile
    • Avatar upload
    • Preferences

Documentation​

  • Backend README: backend/README.md
  • Integration Guide: docs/backend-integration.md
  • Deployment Guide: docs/deployment.md
  • Architecture: Reference V4 at docs/v4-reference/

Key Decisions​

Why Rust/Actix-web?

  • High performance (comparable to V4)
  • Memory safety
  • Excellent FoundationDB bindings
  • Low resource usage for Cloud Run

Why FoundationDB?

  • ACID transactions
  • Multi-tenant data isolation
  • Horizontal scalability
  • Battle-tested (Apple production use)

Why Cloud Run?

  • Serverless (scale to zero)
  • Pay per use
  • Fast cold starts (~1s)
  • Easy integration with GCP services

Success Criteria Met ✅​

  • JWT authentication working
  • User registration and login
  • FoundationDB persistence
  • Session management
  • Multi-tenant isolation
  • Docker containerization
  • Cloud Build configuration
  • Frontend integration updated
  • Documentation complete

Backend API (Phase 2/3) is production-ready for authentication and session management.

Next: Add file operations, MCP, and A2A endpoints in Phase 4+.