PROMPTLY
SOCRATIC
SPECS
Socratic AI requirements workspace built on FastAPI and Anthropic Claude. Cross-examines fuzzy product language, extracts structured specs, keeps a logic graph and PRD in sync, and freezes shareable developer handoffs — not another generic AI writer.
"Natural language is lossy—so the product interrogates it until the spec is graph-backed and testable."
Non-technical founders often ship intent that reads like poetry; engineers inherit contradictions, missing edge cases, and flat docs disconnected from dependencies. Promptly is a Socratic environment: you describe the product in prose, the assistant challenges vague terms and conflicts, and the system materializes a synchronized trio—a dependency-aware logic graph, a living PRD with stories and acceptance criteria, and versioned public snapshots teams can comment on. Marketing already ships interactive demos of the core loops; the FastAPI backend and PostgreSQL model follow a modular roadmap until the full product matches the intended end state.
I own product architecture and implementation: async SQLAlchemy schemas and migrations, FastAPI routers (auth, projects, chat, graph, documents, score, stack, sharing), WebSocket chat with cookie-based auth and project ownership checks before accept, and client-side graph layout patterns (dagre positions persisted server-side only). Frontend uses Vite + React + Tailwind with a strict UX contract—no dead async states, semantic tokens, and security-first cookies instead of Bearer tokens in localStorage.
hover to explore
PROMPTLY SOCRATIC SPECS system architecture: Browser (httpOnly cookies); React + Vite (Zustand · React Flow); Nginx (TLS · WS upgrade); Sentry (errors · perf traces); FastAPI (Uvicorn · async); Claude Agents (5 services · stream); Redis (rate-limit · cache); Celery (async generations); PostgreSQL 17 (asyncpg · Alembic); Google OAuth (Server-side flow); Anthropic API (claude-sonnet-4-6).
Connections: Browser → React + Vite (HTTPS · SPA bundle); React + Vite → Nginx (REST · cookie auth); React + Vite → Nginx (WS · 4 channels); Nginx → FastAPI (proxy_pass /api); FastAPI → Redis (slowapi · cache); FastAPI → PostgreSQL 17 (SQLAlchemy 2 async); FastAPI → Claude Agents (AsyncAnthropic); FastAPI → Google OAuth (httpx OAuth); FastAPI → Sentry (exception · trace); Claude Agents → Anthropic API (messages.stream()); Redis → Celery (BRPOP); Celery → Anthropic API (messages.create()); Celery → PostgreSQL 17 (save results).
Protocol & extraction design
Defined assistant behaviors for vague-term detection with a resolvable ambiguity list, machine-tagged conflicts against prior specs, edge-case hunts, and structured extraction (IDs, user stories, AC, CRUD hints, dependency edges). Wired outputs so graph semantics and narrative sections derive from the same source of truth, enabling a cumulative consistency score with penalties for open ambiguities and blocked nodes.
Realtime platform shell
Implemented project-scoped WebSocket streams for responsive chat—not SSE—so channels can evolve to richer bidirectional events. Enforced `/api`-prefixed product routes plus health and docs conventions. Authentication uses Google OAuth and JWT-backed httpOnly cookies; the React shell coordinates state through a single auth store while every socket upgrade re-validates session and ownership.
Handoff surfaces & roadmap
Designed snapshotting that freezes PRD JSON, graph JSON, and score behind tokenized public URLs with developer feedback anchored on stable spec IDs. Planned advanced lanes (stack matchmaking, wireframe exploration, versioning narrative) integrate after chat, graph, and living-document modules converge, following the staged module sequencing in the repo so each layer consumes real artifacts instead of mocks.