SOMANADH.OS

A portfolio usually asks a recruiter to trust a PDF. I wanted a place where the claim and the proof are the same artifact: the assistant answers from verified records, the analytics are real, and the interface is the engineering sample.

It demonstrates the whole path of an AI feature — prompt design, retrieval, streaming transport, failure fallbacks, rate limits, privacy boundaries — instead of a UI wrapped around an API key.

Next.js App Router renders content and proxies every browser request to a FastAPI service. The browser only ever talks to first-party routes, so the OpenRouter key never leaves the server. FastAPI owns content, retrieval, analytics ingestion, admin sessions, and uploads; SQLAlchemy talks to SQLite locally and Postgres in production. The admin dashboard reads aggregated SQL, and live presence streams over Server-Sent Events.

Content is seeded from a single JSON source of truth into content tables and re-read at request time, so the studio updates the site without a deploy. The assistant builds a knowledge base from those records, retrieves by lexical relevance plus intent, and streams answers through an SSE pipeline. Without an OpenRouter key it answers deterministically from the same records instead of pretending to call a model.

• Keeping a visually heavy homepage fast: the neural scene is lazy-loaded, capped at a modest device pixel ratio, paused off-screen, and replaced by a static composition for reduced-motion visitors.
• Making the assistant honest: the unverified project records had to produce an explicit 'not published yet', not a plausible invention.
• Analytics that respect visitors: anonymous identifiers, consent gating, no raw IP storage, and country data only when the host provides it.

• Server-side proxy instead of exposing the API directly, so credentials and cookies stay off the client.
• Structured lexical retrieval instead of pgvector: with a corpus this small, embeddings would add infrastructure without improving grounded answers.
• Deterministic fallback answers as a first-class mode, not an error screen.
• SSE for streamed answers and live admin pulses: no WebSocket infrastructure for a single-instance dashboard.

• The hard part of an AI feature is the boundary: what the model may say, what happens when it fails, and what the system refuses to do.
• Performance is an art-direction problem — the most expensive effect is usually not the one carrying the concept.

• Deploy the frontend and API, then publish verified screenshots and a walkthrough.
• Add a project-level architecture viewer with per-node explanations.
• Move rate limiting to Redis if the API runs on more than one instance.