🌉 ContextBridge

AI-powered work context continuity dashboard for developers

ContextBridge keeps your work context alive between sessions — across daily standups, project switches, and team handoffs. It automatically generates standup reports from your GitHub activity, lets you log notes/decisions/blockers in a structured feed, and answers natural-language questions about your work history.

---

✨ Features

• 🤖 AI Standup Generator — One-click daily standup reports synthesized from your GitHub commits, PRs, and logged notes
• 📝 Context Log — Capture notes, decisions, blockers, and wins in a structured, searchable feed
• 🔍 Ask AI — Natural-language Q&A over your entire work history ("What decision did we make about the database?")
• 🐙 GitHub Sync — Pull recent commits, PRs, and reviews from any public/private GitHub repo or user
• 📊 Full-text search — Quickly find past entries by keyword
• 🚀 Demo mode — Works fully without an OpenAI key (uses smart mock responses)

---

🏗️ Architecture

Layer	Technology
Frontend	Next.js 14, TypeScript, Tailwind CSS, TanStack Query
Backend	FastAPI, Python 3.12, async/await
Database	SQLite (dev) / PostgreSQL (prod) via SQLAlchemy async
AI	OpenAI GPT-4o-mini (mock fallback available)
GitHub	GitHub REST API v3 (no extra libraries)
Deployment	Docker + docker-compose, GitHub Actions CI

---

🚀 Quick Start

Option A: Docker Compose (recommended)

# Clone and configure
cp .env.example .env
# Edit .env — add OPENAI_API_KEY and GITHUB_TOKEN if you have them

# Start everything
docker-compose up --build

Open http://localhost:3000 for the UI. API docs at http://localhost:8000/api/docs.

Option B: Manual

Backend:

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # configure as needed
uvicorn src.backend.main:app --reload --port 8000

Frontend:

cd src/frontend
npm install
npm run dev

---

⚙️ Configuration

Variable	Default	Description
DATABASE_URL	sqlite+aiosqlite:///./context_bridge.db	SQLAlchemy async DB URL
OPENAI_API_KEY	(mock mode if unset)	OpenAI API key for AI features
AI_MODEL	gpt-4o-mini	OpenAI model to use
GITHUB_TOKEN	(optional)	GitHub PAT for private repos / higher rate limits
NEXT_PUBLIC_API_URL	http://localhost:8000	Backend URL for frontend

---

📡 API Reference

Interactive docs at /api/docs (Swagger UI) and /api/redoc.

Context Entries

Method	Path	Description
GET	/api/context/	List entries (filterable by type, project)
POST	/api/context/	Create entry
GET	/api/context/{id}	Get entry
PATCH	/api/context/{id}	Update entry
DELETE	/api/context/{id}	Delete entry
GET	/api/context/search/?q=...	Search entries

Standup

Method	Path	Description
POST	/api/standup/generate	Generate AI standup for a date
GET	/api/standup/	List reports
GET	/api/standup/{date}	Get report by date
PATCH	/api/standup/{date}	Edit/finalize report

GitHub

Method	Path	Description
GET	/api/github/events	List synced events
POST	/api/github/sync/user	Sync user's public activity
POST	/api/github/sync/repo	Sync specific repo commits/PRs

AI Query

Method	Path	Description
POST	/api/query/ask	Ask a question
GET	/api/query/history	Get Q&A history

---

🧪 Running Tests

# Install test deps (included in requirements.txt)
pytest tests/ -v

# With coverage
pip install pytest-cov
pytest tests/ --cov=src/backend --cov-report=term-missing

---

🤝 Contributing

1. Fork the repo
2. Create a feature branch: git checkout -b feat/your-feature
3. Write tests for new functionality
4. Run pytest and fix any failures
5. Submit a PR

---

📋 Known Limitations

• Vector/semantic search not yet implemented — search uses SQL LIKE (keyword only). Future: integrate pgvector or Chroma for semantic similarity
• Authentication not included — suitable for personal/local use. For team deployments, add an auth layer (e.g. NextAuth, Clerk, or JWT)
• PostgreSQL async driver (asyncpg) must be installed separately for production use: pip install asyncpg
• Frontend requires npm run build to be served statically; in development it runs on port 3000 separately from the backend

---

📄 License

MIT © 2026 — See LICENSE

---

🗓️ Changelog

v1.0.0 (2026-03-14)

• Initial release
• Context log with CRUD and search
• AI standup generation (OpenAI + mock fallback)
• GitHub activity sync
• AI Q&A over work history
• Docker + GitHub Actions CI