ContinuityX-AI (AKF Workspace)

ContinuityX-AI is a developer-assistant workspace that can:

• ingest a GitHub repository,
• build a repo "identity" and developer persona from code + commits,
• power persona-style chat with memory,
• and expose repo intelligence through Search, Wiki, Dependencies, and Timeline views.

---

What You Get

• Fast ingestion with early usability
  • Background job with live progress
  • Two-phase pipeline (partial_ready first, ready later)
• Developer Persona Chat
  • Answers in first-person "author voice"
  • Session memory via Redis
  • Response level dial: Simple, Normal, Expert
• Semantic Code Search (/search)
• Auto-generated Wiki (/wiki)
• Dependency Graph (/deps)
• Commit Timeline + Retrieved Context visibility (/chat)
• Bookmark + Export Q&A as Markdown
• Decision Log (/decisions)
• Onboarding Path Generator (/onboarding)
• Knowledge Handoff Report (/handoff)
• Codebase Health Snapshot (/codehealth)

---

Tech Stack

• Backend: FastAPI
• Frontend: React + Vite
• LLM: Groq (llama-3.3-70b-versatile by default)
• Embeddings: sentence-transformers (local by default, HF endpoint optional)
• Vector DB: ChromaDB
• Chat Memory: Redis
• Containerization: Docker Compose

---

Project Structure

backend/        FastAPI app, ingestion agents, routers, services
frontend/       React app (Dashboard, Chat, Search, Wiki, Deps, Decisions, Onboarding, Handoff, CodeHealth, Settings)
infrastructure/ docker-compose.yml
docs/           architecture + API notes
evaluation/     benchmark helper scripts

---

Ingestion Pipeline (How It Works)

Status Lifecycle

idle -> running -> partial_ready -> ready (or error)

• running: cloning/walking/embedding in progress.
• partial_ready: core context is already indexed; chat can start.
• ready: deep pass finished.

Two-Phase Strategy

Phase A: Fast Pass

• Clones repo with:
  • depth=50
  • single_branch=True
• Indexes priority files first:
  • README files
  • entrypoints (main.py, app.py, index.js, etc.)
  • markdown/docs
  • key config files (.env, requirements.txt, package.json, docker-compose*)
• Indexes first commit batch
• Marks ingestion partial_ready so users can chat immediately

Phase B: Deep Pass

• Processes remaining files in batches of 20
• Updates progress continuously
• Finishes as ready

Large Repo Guards

• Max eligible files: 500 (smallest files prioritized)
• Skip dense dirs with more than 100 files
• Max indexed docs: 2000
• Vector writes are batched (50 docs per add)

Fresh Repo Guarantee

• New ingest request supersedes currently running job
• Chroma stale-data protection uses:
  • Chroma API delete attempt
  • automatic collection rotation fallback
• Prevents "old repo context leaking into new repo"

---

UI Routes

• / Dashboard
  Start ingestion, watch live progress
• /chat
  Persona chat + repo intelligence sidebar (identity, graph, context, commits)
• /search
  Semantic code search cards
• /wiki
  Auto-generated markdown wiki with export
• /deps
  Force-directed dependency map
• /decisions
  Save, browse, filter, delete, and export ADR-style decisions
• /onboarding
  AI-generated 4-session learning path for the current repo
• /handoff
  Author-specific transition report for developer offboarding/handover
• /codehealth
  AI-interpreted health snapshot with score, grade, risks, and quick wins
• /settings
  App settings

---

Backend API

• POST /ingest/
  Start ingestion job (non-blocking)
• GET /ingest/status
  Poll current ingestion state
• GET /ingest/commits
  Commit docs used by timeline
• POST /chat/
  Persona chat (query, session_id, level)
• GET /search/?q=...&k=...
  Semantic retrieval
• GET /wiki/ and POST /wiki/generate
• GET /deps/
• POST /decisions/, GET /decisions/, DELETE /decisions/{id}, GET /decisions/export
• GET /onboarding/, POST /onboarding/generate
• GET /handoff/authors, POST /handoff/generate
• GET /codehealth/, POST /codehealth/generate
• GET /health

---

Prerequisites

• Docker Desktop (Linux engine enabled)
• Docker Compose
• Groq API key (recommended for real responses)

---

Environment Setup

Create a root .env file at: E:\python\ContinuityX-AI\.env

Example:

# Required for real LLM output
GROQ_API_KEY=your_groq_key

# Optional
GROQ_MODEL=llama-3.3-70b-versatile
EMBEDDING_BACKEND=local
HF_API_TOKEN=
CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000,http://localhost:8000
REDIS_URL=redis://redis:6379

# Frontend to Backend production URL
VITE_API_URL=http://localhost:8000

---

Run (Recommended: Docker)

Windows PowerShell

Set-Location E:\python\ContinuityX-AI
docker compose -f infrastructure/docker-compose.yml up --build

Open:

• Frontend: http://localhost:3000
• Backend Docs (Swagger): http://localhost:8000/docs
• Health: http://localhost:8000/health

---

Production Deployment

You can deploy the backend to Render and the frontend to Vercel.

Backend (Render)

1. Link your repository to Render.
2. The included render.yaml will automatically deploy:
   • A Redis instance (free tier).
   • The FastAPI backend.
3. Add your GROQ_API_KEY, CORS_ORIGINS, and REDIS_URL in the Render dashboard environment variables for the backend service.

Frontend (Vercel)

1. Link your repository to Vercel.
2. Set the "Root Directory" to frontend.
3. The included vercel.json provides the required SPA rewrites.
4. Add the VITE_API_URL environment variable pointing to your deployed Render backend URL.

---

First-Time Usage Walkthrough

1. Open Dashboard.
2. Paste a GitHub repo URL (public or private with token).
3. Click Start Ingestion.
4. Watch progress:
   • once it reaches partial_ready, you can move to Chat.
5. Open Chat:
   • ask architecture or implementation questions,
   • inspect retrieved file context and commit timeline,
   • switch response level (Simple/Normal/Expert).
6. Explore:
   • Search tab for semantic snippets
   • Wiki tab to generate markdown wiki
   • Deps tab for import relationships
   • Decisions tab to build a reusable architectural memory
   • Onboarding tab to generate a structured learn-the-codebase plan
   • Handoff tab to generate transition reports for specific commit authors
   • Health tab to generate repo quality snapshot and actionable quick wins
7. Ingest another repo anytime:
   • old run is superseded,
   • new repo state becomes the active one.

---

Troubleshooting

1) .env not found

Create E:\python\ContinuityX-AI\.env.

2) Docker engine/pipe errors on Windows

Start Docker Desktop and ensure Linux containers are enabled.

3) Chat responds with mock output

Set GROQ_API_KEY in .env, then restart containers.

4) Ingestion appears stale

Check GET /ingest/status; if a new repo was submitted, status should reflect the new repo name.

5) No commits/wiki/deps shown

Ingest a repo first; wait for at least partial_ready, then refresh the relevant page.

---

Security Notes

• Never commit .env or API keys.
• If secrets were accidentally pushed, rotate them immediately.
• Keep .gitignore in place and untrack existing secret files with git rm --cached.

---

Current Limitations

• Ingestion state is in-memory (single backend process scope).
• Dependency map currently focuses on Python import relationships.
• Wiki generation is based on retrieved top documents (not full AST reasoning).
• Handoff and health reports are generated from retrieved vectors + commit context and may miss nuances outside indexed chunks.

---

License

See LICENSE.