Evidence-First Engineering Knowledge System

Problem

A portfolio can make claims without making them easy to verify. A generic chatbot creates the opposite risk: confident answers that outrun the evidence. This system was designed to make engineering work fast to inspect while keeping every AI answer inside a public, reviewable knowledge boundary.

Architecture

• GitHub Pages serves the static portfolio, project case studies, Insights, résumé, newsletter, and accessible interaction layer.
• Markdown in Git is the source of truth for Ask Mantosh. GitHub Actions authenticates indexing with short-lived OIDC credentials.
• Cloudflare Worker validates requests, enforces quotas, handles deterministic greetings and navigation, and coordinates retrieval.
• D1 FTS5 and Vectorize provide lexical and semantic retrieval; reciprocal-rank fusion combines the results.
• Workers AI receives only selected public evidence and returns structured answers with approved citations.

Engineering decisions

• Evidence before generation. If retrieval finds no sufficiently grounded source, the system declines instead of answering from model memory.
• Deterministic paths before AI. Greetings and courtesies receive concise replies without retrieval or AI; Resume, Contact, project, and latest-article commands navigate directly.
• No browser secret. The public client holds no provider credential; indexing is isolated from visitor traffic and authenticated separately.
• Fail closed. The mandatory rate limiter, bounded input, exact-origin CORS, public-visibility filtering, and citation allowlist protect the public boundary.
• Automate release confidence. SEO, discoverability, links, accessibility, documentation drift, content inventory, and Worker behavior are checked before publication.

Evidence and limits

The implementation, public knowledge corpus, automated tests, release gates, and production-state documentation are available in the repository for inspection.

Current limits: GitHub Pages rather than a custom domain, Cloudflare free-tier quotas, no declared staging environment, no formal accessibility conformance audit, and no labeled offline retrieval-evaluation set.