Skip to content

Home

Jump to bottom
Kayvan Shah edited this page Aug 21, 2025 · 2 revisions

🧭 Project Plan (Dev-Facing)

Stack: FastAPI, async SQLAlchemy, JWT + API Key, SQLite→Postgres (later), FastMCP, OpenRouter, React + Vite, shadcn/ui, Tailwind, TanStack Query, React Hook Form + Zod, Axios, Pytest, Pytest-asyncio, Playwright

Legend: ✅ done / 🚧 in progress / ⏳ planned

1) Backend API (FastAPI)

Core Auth & Users

  • ✅ Sign up /signup (hashed pw), token /token (OAuth2 Password)

  • ✅ Dual auth on protected routes (JWT + X-API-Key)

  • ⏳ Update profile: PUT /users/me (username, email, display_name; partial via PATCH)

  • ⏳ Email verification:

    • POST /auth/request-verification → email code/link
    • POST /auth/verify → confirm code/token
    • Store email_verified: bool, verification_token, expiry, attempts

  • ⏳ API key mgmt per-user:

    • POST /apikeys (create/rotate), GET /apikeys (list masked), DELETE /apikeys/{id}
    • Hash keys at rest, show once on creation
    • Soft‑revoke + hard‑delete; record lastUsedAt

Tasks

  • ✅ CRUD: /tasks (self‑scoped)

  • ⏳ Extras:

    • Filtering/pagination/sort: /tasks?status=&q=&page=&limit=
    • Bulk ops: POST /tasks/bulk (create/update status)
    • Tags & relations: /tasks/{id}/related (for agent features)
    • “Closest task” by fuzzy title/embedding (stub now; agent can approximate)

Security & Ops

  • ⏳ Rate limiting (per JWT + per API key)
  • ⏳ Audit log table (who did what, when, IP/user‑agent)
  • ⏳ Structured errors (Problem+JSON)
  • ⏳ Settings split (env‑driven), CORS config, health checks /healthz, /readyz

2) MCP Server & Agent Integration

Runtime & Lifespan

  • ⏳ Start MCP server inside FastAPI lifespan (shared process):

    • On startup: init FastMCP server, register tools, warm LLM client
    • On shutdown: graceful stop

  • ⏳ /ask-agent endpoint:

    • Request: { query, mode?, history?[], toolPrefs?, top_k? }
    • Response: { answer, usedTools[], steps[], citations[], latency_ms }
    • Short conversation history kept (server‑side ring buffer; truncate + redact secrets)

Tools (FastMCP)

  • ⏳ list_tasks({status?, q?, limit?})
  • ⏳ list_related_tasks({task_id})
  • ⏳ get_closest_task({title}) (string‑matching first; later upgrade to embeddings)
  • ⏳ create_task({title, description?, status?})
  • ⏳ update_task({id, title?, description?, status?})
  • ⏳ update_task_status({id, status})
  • ⏳ delete_task({id})

LLM (OpenRouter)

  • ⏳ Use cost‑free OSS models when available; configurable model name per request/env

  • ⏳ Safe tool‑use policy: tool call budget, timeouts, retries, and guardrails

  • ⏳ “Reasoning trace”:

    • Return a concise step summary (steps[]) for frontend display (no sensitive data)
    • Store full raw trace server‑side only for debugging (behind admin flag)

Starter System Prompt (drop‑in)

You are Taskaza Agent. You can call tools to manage tasks. Prefer exact tool calls over free‑text answers. If the user’s intent is CRUD, call a tool. Keep responses concise. Always summarize result for the user after tools execute. Available tools: list_tasks, list_related_tasks, get_closest_task, create_task, update_task, update_task_status, delete_task. If unsure, ask a minimal clarifying question.

3) Frontend (React + shadcn/ui)

Screens

  • ⏳ Landing page: product blurb + CTA

  • ⏳ Auth: Signup/Login (JWT retrieval + API key capture)

  • ⏳ Dashboard:

    • AskBar (agent input) with streaming answer + compact Reasoning Trace panel
    • Tasks list (cards/table), filters, sort, pagination
    • Buttons for manual CRUD; inline edit for status
    • Toasts: “task created/updated/deleted/found”

  • ⏳ Profile/Settings:

    • Update user details
    • Email verification flow (send/verify)
    • API key management (create/rotate/revoke, copy‑once view)

Client Tech

  • ⏳ TanStack Query for API state + retries
  • ⏳ React Hook Form + Zod for validation
  • ⏳ Axios client with JWT + API key interceptors
  • ⏳ Toasts via shadcn/ui; Dialogs for destructive ops
  • ⏳ Mobile‑first, dark mode friendly

4) Testing

Backend

  • ⏳ Pytest + pytest‑asyncio:

    • Auth flow (signup/token), 401/403 cases (missing/invalid JWT, API key)
    • Users: update + verification token lifecycle
    • Tasks: CRUD, self‑scoping, filters, bulk
    • MCP tools: unit tests on each tool function (mock DB), budget timeouts
    • /ask-agent: integration tests (mock LLM) asserting tool selection + final answer

  • ⏳ Load smoke: locust or pytest-benchmark for hot paths

Frontend

  • ⏳ Playwright:

    • Auth forms, CRUD happy paths, toasts appear
    • AskBar → shows answer + reasoning trace; handles errors/retries

5) Observability & DevEx

  • ⏳ Logging: structlog/json logs with request IDs; tool call spans
  • ⏳ Metrics: Prometheus counters/timers (requests, tool calls, LLM latency, errors)
  • ⏳ Feature flags: enable/disable agent, reasoning trace verbosity
  • ⏳ Seed script: demo users, sample tasks
  • ⏳ Makefile/dev containers for easy spin‑up

6) Deployment

  • ⏳ Envs: OPENROUTER_API_KEY, JWT_SECRET, API_KEY_SALT, SMTP creds

  • ⏳ SQLite (dev) → Postgres (prod) migration path (Alembic)

  • ⏳ CI:

    • Lint + type check
    • Run tests
    • Build images
    • Deploy (Render/Railway) with health checks

  • ⏳ CD: blue/green or rolling where possible

7) Docs

  • ⏳ README quick‑start (Postman collection, curl examples)
  • ⏳ Auth guide (JWT + API key, where to put each header)
  • ⏳ Agent guide (how /ask-agent works, sample prompts)
  • ⏳ MCP tool reference (inputs/outputs, examples)
  • ⏳ Security notes (rate limiting, audit logs, key rotation)

What’s Missing / To Add (MCP side)

  • Tool budget/timeouts + deterministic retries
  • Compact reasoning trace format + PII‑redaction rules
  • Guard against infinite tool loops
  • Model fallback sequence (OSS→fallback)
  • Cached list_tasks for quick UI suggestions (e.g., “recent tasks”)

Suggested Milestones

  1. M0 – MCP Skeleton: FastMCP server in lifespan, /ask-agent, stub tools, mock LLM
  2. M1 – Tools & Tests: Implement all tools + unit tests; /ask-agent integration test
  3. M2 – Frontend AskBar: Render answers + reasoning trace; basic tasks UI + toasts
  4. M3 – Email + API Keys: Verification flow, key rotate/revoke; settings UI
  5. M4 – Perf & Observability: Rate limiting, metrics, logs, caching
  6. M5 – Postgres + CI/CD: Alembic, env hardening, full pipeline green

Clone this wiki locally