oneie/one/things/plans/backend-status.md

Build apps, websites, and AI agents in English. Zero-interaction setup for AI agents (Claude Code, Cursor, Windsurf). Download to your computer, run in the cloud, deploy to the edge. Open source and free forever.

---
title: Backend Status
dimension: things
category: plans
tags: ai, auth, backend, convex, frontend
related_dimensions: connections, events, groups, knowledge, people
scope: global
created: 2025-11-03
updated: 2025-11-03
version: 1.0.0
ai_context: |
  This document is part of the things dimension in the plans category.
  Location: one/things/plans/backend-status.md
  Purpose: Documents backend status: what's complete, what's next
  Related dimensions: connections, events, groups, knowledge, people
  For AI agents: Read this to understand backend status.
---

# Backend Status: What's Complete, What's Next

**Date:** 2025-10-24
**Status:** ✅ Foundation Complete, 🚧 Features In Progress
**Version:** 1.0.0

---

## Executive Summary

The ONE Platform backend is **fully functional with Better Auth integration**. The connection between frontend and backend is working. Here's what exists and what's next.

---

## ✅ COMPLETE: What Already Works

### 1. Authentication Backend (Working)

**Location:** `/backend/convex/auth.ts`

**Implemented:**

- ✅ Email/Password signup
- ✅ Email/Password signin
- ✅ Sign out
- ✅ JWT token generation (access + refresh)
- ✅ Password hashing (SHA-256 for demo, needs bcrypt for production)
- ✅ Email verification token generation
- ✅ Rate limiting (5 mutations per second)
- ✅ Sessions table with token validation

**Current Flow:**

```
Frontend (Better Auth) → POST /auth/signup
  ↓
Backend (auth.ts) → Hash password, create user, generate JWT
  ↓
Frontend stores JWT → Uses for subsequent requests
```

### 2. Database Schema (Complete)

**Location:** `/backend/convex/schema.ts`

**Tables:**

- ✅ users (email, passwordHash, emailVerified)
- ✅ sessions (userId, token, expiresAt)
- ✅ groups (slug, name, type, parentGroupId, settings)
- ✅ entities (groupId, type, name, properties, status)
- ✅ connections (groupId, type, fromId, toId, metadata)
- ✅ events (groupId, type, actorId, targetId, timestamp)
- ✅ knowledge (groupId, type, text, embedding, metadata)

**Status:**

- ✅ Schema defined
- ✅ All 6 dimensions represented
- ✅ Indexes created for common queries
- ⚠️ Missing: apiKeys table (for API key authentication)

### 3. Frontend Auth Integration (Working)

**Location:** `/web/src/lib/auth-client.ts`

**Components:**

- ✅ Better Auth client configured
- ✅ Auth hooks (useSession, useSignIn, useSignUp)
- ✅ Auth page (`/account/auth.astro`)
- ✅ Tests for auth flows (50+ test cases)
- ✅ OAuth configuration (Google, GitHub)

**Test Coverage:**

- ✅ Email/password signup
- ✅ Email/password signin
- ✅ Session management
- ✅ Token refresh
- ✅ OAuth flows

### 4. Core Mutations (Partial)

**Location:** `/backend/convex/mutations/`

**Implemented:**

- ✅ entities.ts (create, update, delete things)
- ✅ groups.ts (create, update groups)
- ✅ connections.ts (create, delete relationships)
- ✅ contact.ts (contact form submissions)
- ✅ onboarding.ts (user onboarding)

**Status:**

- ✅ Basic CRUD for core entities
- ⚠️ Missing: Full 66 thing types
- ⚠️ Missing: Event logging on mutations
- ⚠️ Missing: Group scoping enforcement

### 5. Core Queries (Partial)

**Location:** `/backend/convex/queries/`

**Implemented:**

- ✅ entities.ts (list, get things)
- ✅ groups.ts (list, get groups)
- ✅ connections.ts (list connections)
- ✅ ontology.ts (get available types)
- ✅ init.ts (initialization data)

**Status:**

- ✅ Basic read operations
- ⚠️ Missing: Vector search for RAG
- ⚠️ Missing: Complex filtering/sorting

### 6. Services (Partial)

**Location:** `/backend/convex/services/`

**Implemented:**

- ✅ ontologyMapper.ts (map features to ontology)
- ✅ websiteAnalyzer.ts (analyze existing websites)
- ✅ brandGuideGenerator.ts (generate brand guides)
- ✅ featureRecommender.ts (recommend features)

**Status:**

- ✅ Specialized services working
- ⚠️ Missing: General CRUD services
- ⚠️ Missing: RAG service
- ⚠️ Missing: AI SDK integration

---

## 🚧 IN PROGRESS: What Needs Work

### 1. HTTP API Layer (NOT STARTED)

**Needed:** Hono HTTP endpoints for external access

**What's Missing:**

- [ ] `/backend/convex/http.ts` - Hono setup
- [ ] API key authentication middleware
- [ ] REST endpoints for all 6 dimensions
- [ ] OpenAPI documentation
- [ ] Rate limiting per group
- [ ] CORS configuration

**Priority:** HIGH - Required for multi-client support

**Estimated Effort:** 1-2 weeks

### 2. API Key Management (NOT STARTED)

**Needed:** API key generation and validation

**What's Missing:**

- [ ] apiKeys table in schema
- [ ] createApiKey mutation
- [ ] verifyApiKey query
- [ ] revokeApiKey mutation
- [ ] API key middleware in Hono

**Priority:** HIGH - Needed for external access

**Estimated Effort:** 3-4 days

### 3. Event Logging (PARTIAL)

**Current:** Events table exists, but not auto-logged

**What's Missing:**

- [ ] Auto-log events on all mutations
- [ ] Event filtering/search
- [ ] Timeline views
- [ ] Event retention policies

**Priority:** MEDIUM - Important for audit trail

**Estimated Effort:** 1 week

### 4. Group Scoping (PARTIAL)

**Current:** Groups table exists, but not enforced

**What's Missing:**

- [ ] Middleware to extract groupId from auth
- [ ] Enforce groupId on all queries/mutations
- [ ] Hierarchical group access (parent → child)
- [ ] Resource quotas per group

**Priority:** MEDIUM - Critical for multi-tenancy

**Estimated Effort:** 1 week

### 5. AI SDK Integration (NOT STARTED)

**Needed:** RAG pipeline and AI features

**What's Missing:**

- [ ] Install AI SDK: `npm install ai @ai-sdk/openai`
- [ ] RAG ingestion (document chunking)
- [ ] Vector embeddings (OpenAI embedding model)
- [ ] Vector search query
- [ ] Generation action (with context)
- [ ] Streaming support

**Priority:** MEDIUM - Needed for AI features

**Estimated Effort:** 2 weeks

### 6. Better Auth Expansion (PARTIAL)

**Current:** Email/password + basic OAuth setup

**What's Missing:**

- [ ] Magic links
- [ ] Email verification (UI/API)
- [ ] Password reset flow
- [ ] 2FA (TOTP)
- [ ] Session management (revoke, list)
- [ ] OAuth provider expansion

**Priority:** MEDIUM - Improve security/UX

**Estimated Effort:** 1-2 weeks

### 7. Complete CRUD (PARTIAL)

**Current:** Basic CRUD for ~5-10 entity types

**What's Missing:**

- [ ] CRUD mutations for all 66+ thing types
- [ ] CRUD for 25 connection types
- [ ] Bulk operations
- [ ] Batch mutations

**Priority:** MEDIUM - Needed for feature completeness

**Estimated Effort:** 2-3 weeks

### 8. Production Hardening (NOT STARTED)

**What's Missing:**

- [ ] Use bcrypt instead of SHA-256 for password hashing
- [ ] Input validation on all endpoints
- [ ] SQL injection prevention (already handled by Convex)
- [ ] Rate limiting tuning
- [ ] Security headers
- [ ] HTTPS enforcement

**Priority:** HIGH - Critical for production

**Estimated Effort:** 1 week

---

## Architecture: Current State

```
┌──────────────────────────────────┐
│   FRONTEND (Astro + React)       │
│  Better Auth Components          │
│  ✅ Working & Tested             │
└────────────┬─────────────────────┘
             │ JWT Token
             ↓
┌──────────────────────────────────┐
│  CONVEX FUNCTIONS (Current)      │
│  ✅ Auth (signup/signin/signout) │
│  ✅ Basic CRUD (groups, things)  │
│  ⚠️ Missing: HTTP API            │
│  ⚠️ Missing: RAG/AI              │
└────────────┬─────────────────────┘
             │
             ↓
┌──────────────────────────────────┐
│  CONVEX DATABASE (Complete)      │
│  ✅ 6-dimension ontology schema  │
│  ✅ All tables with indexes      │
│  ⚠️ Missing: apiKeys table       │
└──────────────────────────────────┘
```

**Gap:** Frontend currently uses Convex hooks directly. Need HTTP API for:

- External clients (mobile, desktop, CLI)
- Third-party integrations
- Easier client library generation

---

## Next Priority: What to Build First

### Phase 1: HTTP API Layer (Weeks 1-2)

**Goal:** Make backend accessible via REST API

**Steps:**

1. Install Hono: `npm install hono`
2. Create `http.ts` with Hono app
3. Add API key authentication
4. Implement `/api/health` endpoint
5. Add rate limiting middleware
6. Set up CORS

**Deliverable:** External clients can call `/api/health`

### Phase 2: API Key Management (Week 3)

**Goal:** Enable API key-based authentication

**Steps:**

1. Add `apiKeys` table to schema
2. Create `createApiKey` mutation
3. Create `verifyApiKey` query
4. Add API key middleware
5. Test with curl/Postman

**Deliverable:** Can generate and use API keys

### Phase 3: CRUD Endpoints (Weeks 4-5)

**Goal:** All 6 dimensions accessible via REST

**Steps:**

1. Implement 37 REST endpoints
2. Add input validation
3. Add error handling
4. Add pagination
5. Add filtering/sorting

**Deliverable:** Full REST API for all ontology dimensions

### Phase 4: AI SDK Integration (Weeks 6-7)

**Goal:** RAG pipeline working

**Steps:**

1. Install AI SDK
2. Implement ingestion (chunking)
3. Add embeddings
4. Add vector search
5. Add generation with context

**Deliverable:** `/api/ai/search` and `/api/ai/generate` working

### Phase 5: Production Hardening (Week 8)

**Goal:** Production-ready backend

**Steps:**

1. Use bcrypt for passwords
2. Add input validation
3. Tune rate limits
4. Set up monitoring
5. Security audit

**Deliverable:** Backend ready for production deployment

---

## Code Quality Assessment

### ✅ What's Good

1. **Schema Design** - Clean, normalized, well-indexed
2. **Type Safety** - Full TypeScript with Convex types
3. **Error Handling** - Rate limiting, duplicate checking
4. **Testing** - 50+ auth tests with good coverage
5. **Documentation** - Schema well-commented
6. **Multi-tenancy Foundation** - Groups table ready

### ⚠️ What Needs Improvement

1. **Password Hashing** - SHA-256 demo → needs bcrypt
2. **Event Logging** - Not auto-logged on mutations
3. **Input Validation** - Minimal validation
4. **Error Messages** - Generic error handling
5. **API Documentation** - No OpenAPI spec
6. **Tests** - Only auth tested, need full coverage

---

## Commands to Get Started

### Install Dependencies

```bash
cd backend
npm install hono @ai-sdk/openai ai bcryptjs zod
```

### Create HTTP Layer

```typescript
// /backend/convex/http.ts
import { Hono } from "hono";
import { cors } from "hono/cors";
import { handle } from "hono/vercel";
import { httpRouter } from "convex/server";

const app = new Hono();
app.use("*", cors());

app.get("/api/health", (c) => {
  return c.json({ status: "ok" });
});

export default httpRouter({
  "/": handle(app),
});
```

### Test It

```bash
# Start dev server
npx convex dev

# Test endpoint
curl http://localhost:3000/api/health
# Should return: {"status":"ok"}
```

---

## Key Files to Reference

**Frontend Auth:**

- `/web/src/lib/auth-client.ts` - Auth setup
- `/web/src/pages/account/auth.astro` - Auth page
- `/web/tests/auth/auth.test.ts` - Test examples

**Backend Auth:**

- `/backend/convex/auth.ts` - Auth mutations
- `/backend/convex/auth.config.ts` - Auth config
- `/backend/convex/lib/jwt.ts` - JWT utilities

**Schema:**

- `/backend/convex/schema.ts` - Complete 6-dimension schema
- `/backend/convex/types/ontology.ts` - Generated types

**CRUD Examples:**

- `/backend/convex/mutations/entities.ts` - Example mutations
- `/backend/convex/queries/entities.ts` - Example queries

---

## Team Assignments (Cycle-Based)

**Phase 1 (HTTP API): Cycle 101-120 (3 weeks)**

- Agent-backend: Implement Hono routes
- Agent-backend: Add middleware
- Agent-quality: Write API tests

**Phase 2 (API Keys): Cycle 121-140 (2 weeks)**

- Agent-backend: Schema + mutations
- Agent-frontend: Generate API key UI
- Agent-quality: Security testing

**Phase 3 (CRUD): Cycle 141-160 (2 weeks)**

- Agent-backend: Implement endpoints
- Agent-integrator: Generate OpenAPI
- Agent-quality: Integration tests

**Phase 4 (AI SDK): Cycle 161-180 (2 weeks)**

- Agent-backend: RAG pipeline
- Agent-quality: RAG tests
- Agent-documenter: API docs

**Phase 5 (Production): Cycle 181-200 (1 week)**

- Agent-ops: Monitoring setup
- Agent-clean: Code review
- Agent-documenter: Final docs

---

## Success Metrics

After Phase 1 (HTTP API):

- ✅ `/api/health` returns 200
- ✅ External clients can query backend
- ✅ Rate limiting working

After Phase 2 (API Keys):

- ✅ Can generate API key
- ✅ API key authentication working
- ✅ Group-scoped requests

After Phase 3 (CRUD):

- ✅ All 37 REST endpoints working
- ✅ Input validation passing
- ✅ Error handling consistent

After Phase 4 (AI SDK):

- ✅ Vector search working
- ✅ Generation with context working
- ✅ Streaming responses working

After Phase 5 (Production):

- ✅ bcrypt passwords
- ✅ All tests passing
- ✅ OpenAPI documentation
- ✅ Monitoring alerts working

---

## Related Documentation

- **`one/things/plans/backend.md`** - Complete backend architecture plan
- **`one/knowledge/ontology.md`** - 6-dimension specification
- **`CLAUDE.md`** - Development workflow
- **`web/AGENTS.md`** - Convex patterns reference

---

## What's Working Right Now

You can immediately:

1. ✅ Sign up with email/password (frontend)
2. ✅ Sign in with OAuth (Google, GitHub)
3. ✅ Stay logged in (JWT tokens)
4. ✅ Create/update/delete entities (via Convex hooks)
5. ✅ Create/manage groups
6. ✅ View connections and events

What's NOT working yet:

1. ❌ External API access (HTTP)
2. ❌ API key authentication
3. ❌ AI/RAG features
4. ❌ Third-party integrations
5. ❌ Mobile apps (no HTTP API)

---

## Bottom Line

**The foundation is solid.** Backend auth is working, schema is complete, frontend integration is done. The main gaps are:

1. **HTTP API** - Make it accessible externally
2. **AI SDK** - Add RAG/generation features
3. **Production Hardening** - bcrypt, validation, monitoring

Everything else is in place. Build the HTTP layer first (1-2 weeks), then everything else follows naturally.

**Status:** 🟢 Ready to build Phase 1 (HTTP API)