Technical Requirements Document #

TRD v1.0 · ronilprasad8.tech · Full-Stack Portfolio & AI Assistant Platform

1. System Architecture Overview #

The application employs a resilient, high-throughput, hybrid client-server architecture built on Python Flask and modern ES6+ web standards, deployable across serverless environments. The backend orchestrates a multi-tiered concurrency pipeline, multi-key round-robin client pools, in-flight failover, and real-time token streaming to deliver low-latency interactions for "The GOAT" AI assistant.

• Concurrent Multi-Threaded Pre-Fetching: Sequential I/O operations are eliminated by executing Firestore global knowledge queries, episodic memory retrieval, and daemon sports cache lookups in parallel via a concurrent.futures.ThreadPoolExecutor(max_workers=3). This slashes pre-fetch latency from ~750ms sequentially down to 150–200ms concurrently.
• Multi-Key Round-Robin & In-Flight 429 Failover: Both Groq (openai/gpt-oss-120b) and Google Gemini (gemini-2.5-flash) support comma-separated API key pools in environment variables. Keys are parsed at startup into thread-safe client pools (_groq_clients, _gemini_clients) and rotated atomically per request using synchronized indices guarded by thread locks. If the active key hits an HTTP 429 quota ceiling or transient error, the inference engine automatically attempts key N+1 in under 50ms without failing the user request.
• Real-Time Server-Sent Events (SSE) Streaming & Ultra-Low TTFT: The /chat endpoint delivers tokens progressively via text/event-stream. An inverted failover hierarchy routes all requests directly to Groq LPU inference, slashing Time to First Token (TTFT) to <250ms, while maintaining Google Gemini multi-key rotation as a seamless zero-downtime fallback.
• Adaptive 60fps Typewriter Frontend: The browser client decodes streaming chunks using ReadableStreamDefaultReader and TextDecoder, feeding an adaptive 60fps typewriter engine (1–3 chars/frame normal pace, dynamically accelerating to 6–16 chars/frame to catch up or complete) with real-time markdown synthesis.
• Context-Aware Intent Routing & Stream Sanitization: A dual-layer intent recognition system differentiates conversational inquiries from direct technical questions, enforcing a direct structured response policy without conversational preamble for technical queries. The StreamTagFilter provides real-time boundary protection, intercepting internal system directives and administrative memory tags before stream chunks reach the client.
• Asynchronous Daemon Worker: Message audit logs, trigger state updates, and learned fact persistence are offloaded to an asynchronous background executor (_bg_executor), ensuring zero latency impact on user-facing token streams.

---

2. Technology Stack #

Dependency / Tool	Version	Purpose	Source
Flask	3.1.3	Core backend web framework & routing engine.	requirements.txt
groq	1.1.2	Primary ultra-low latency LLM inference engine (openai/gpt-oss-120b) with multi-key round-robin client pool and in-flight HTTP 429 failover (<50ms).	requirements.txt
google-genai	1.72.0	Secondary high-reasoning fallback engine (gemini-2.5-flash) supporting multi-key round-robin client pools and automatic zero-downtime failover.	requirements.txt
concurrent.futures	Python Built-in	Multi-threaded parallel pre-fetching (ThreadPoolExecutor(max_workers=3)) for Firestore facts, memory, and match caches, plus async daemon logging (_bg_executor).	Python Standard Library
Server-Sent Events (SSE)	W3C Standard	Real-time chunked token streaming protocol (text/event-stream) driving the frontend 60fps typewriter engine.	HTTP/1.1 Protocol
Firebase JS SDK	11.0.1 (Unified)	Client-side authentication and Firestore database access.	templates/, static/js/ & package.json
python-dotenv	1.2.2	Loads environment variables from .env file (local dev).	requirements.txt
@vercel/speed-insights	2.0.0	Web performance tracking.	package.json
Gunicorn	25.3.0	WSGI HTTP Server for production deployment.	requirements.txt

---

3. Project Structure #

ronilprasad8/
├── .env                  # Environment variables (Keys: Gemini, Groq, Firebase)
├── .github/              # GitHub Actions workflows / config (if any)
├── CV/                   # Stores static CV.pdf
├── app.py                # Main Flask application entrypoint & routing
├── chatbot.py            # AI Engine logic (Failover, context injection)
├── documentation/        # Project documentation hub (SRS, PRD, TRD, etc.)
├── package.json          # Node dependencies (Vercel speed insights, Firebase)
├── requirements.txt      # Python backend dependencies
├── sitemap.xml           # Static SEO sitemap
├── static/               # Client-side assets
│   ├── css/              # Application stylesheets
│   ├── js/               # Client scripts (chatbot.js)
│   └── images/           # Badges, icons, hero images
├── templates/            # Jinja2 HTML views (index, about, chat, etc.)
├── vercel.json           # Vercel deployment and serverless build configuration
└── workflows/            # Additional pipeline or task definitions

---

4. APIs & Endpoints #

Method	Path	Architectural Handler	Purpose & Security Boundary
GET	/	app:index	Renders index.html (Portfolio Landing). Public.
GET	/about	app:about	Renders about.html. Public.
GET	/project	app:project	Renders project.html. Public.
GET	/contact	app:contact	Renders contact.html (Secure contact interface). Public.
POST	/contact	app:contact	Processes contact form submissions with honeypot bot filtering, sliding-window IP rate limiting (5 req/10 min), sanitization, and async Firestore persistence.
GET	/login	app:login	Renders login.html (Firebase Authentication flow). Public.
GET	/cv	app:view_cv	Serves international ATS-compliant Western CV (CV_Western.pdf) by default; serves regional format via ?format=regional.
GET	/architecture	app:architecture	Renders dedicated architecture.html showcase page (failover pipeline, zero-trust security architecture, and system diagrams). Dedicated server-rendered route.
GET	/privacy	app:privacy	Renders privacy.html (Privacy Policy & Terms of Service). Public.
GET	/chat	app:chat	Renders dedicated chat.html conversational interface. Public.
POST	/chat	app:chat	Dual-Protocol AI Inference & Streaming Gateway: Security & Rate Limiting: Cryptographically validates Authorization Bearer token (RSA-256 Firebase JWT or HMAC SHA-256 guest token). Enforces tiered sliding-window rate limiting (5 req/min guest, 15 req/min authenticated). Concurrent Pre-Fetch: Runs parallel retrieval of Firestore global knowledge facts, episodic memory, and cached sports data via ThreadPoolExecutor(max_workers=3) (<200ms). Context-Aware Output Governance: Detects user query intent to route between conversational dialogue and direct technical answers, eliminating conversational noise for focused technical requests. Multi-Key Round-Robin & Failover: Dispatches across pooled keys for Gemini and Groq. Enforces a 1.2s speculative TTFT window on primary Gemini with instant Groq fallback, plus in-flight HTTP 429 failover (<50ms) to adjacent pool keys. Streaming Protocol (SSE): When requested with Accept: text/event-stream, returns text/event-stream; charset=utf-8 yielding progressive chunks (data: {"chunk": "..."}\n\n) sanitized in real time via StreamTagFilter. Falls back to standard JSON (application/json) for legacy clients. Non-Blocking Async Audit: Offloads message logging, trigger updates, and learned memory extraction to a daemon background worker (_bg_executor) with 0ms delay on the stream.
POST	/api/guest-session	app:guest_session	Mints an ephemeral HMAC SHA-256 signed guest session token for zero-friction interactive preview.
GET	/api/chat/history	app:get_chat_history	Retrieves conversation history for authenticated user UID. Requires valid Bearer JWT.
GET	/sitemap.xml	app:sitemap	Serves generated XML sitemap for search engine crawlers.
GET	/google[id].html	app:google_verify	Serves Google Search Console domain verification.

---

5. Threat Model & Architectural Transparency Policy #

Intentional Security Model (Kerckhoffs's Principle & NIST Open Architecture): The platform's operational architecture is intentionally documented as a public reference implementation. Security guarantees rely strictly on cryptographic primitives, strict server-side authorization enforcement, and defensive data sanitization, never on security through obscurity.

Defensive Layer	Implementation Mechanism	Security Rationale
Authentication	RSA-256 Google ID token verification & HMAC SHA-256 guest session signatures.	Guarantees identity authenticity at the server boundary without trusting client assertions.
Rate Throttling	Tiered sliding-window in-memory throttling (5 req/min guest, 15 req/min authenticated).	Shields upstream LLM endpoints (Gemini / Groq) against denial-of-wallet and scraper exhaustion.
Knowledge Gating	Strict owner-only gating (verified administrative identity) and confirmation review queues.	Prevents visitors or prompt injection attacks from planting false claims in persistent portfolio memory.
Contact Privacy	Server-side contact form with hidden honeypot field and IP throttling replacing raw mailto: and tel: links.	Protects personal phone and email addresses from automated scrapers and spam harvesting.
Configuration Schema	Environment variable specifications documented publicly; secrets stored exclusively in platform vaults.	Separates functional interface documentation from runtime secrets management.

Environment Variable Schemas

Variable Name	Classification	Functional Description
GEMINI_API_KEY	Secret (Vault)	Google Gemini API key(s) enabling primary LLM reasoning. Supports comma-separated keys (key1,key2,...) parsed into a singleton client pool with atomic round-robin dispatch and a 1.2s speculative TTFT window.
GROQ_API_KEY	Secret (Vault)	Groq platform API key(s) powering openai/gpt-oss-120b. Supports comma-separated keys (key1,key2,key3,...) parsed into a thread-safe client pool with synchronized round-robin rotation and automatic in-flight HTTP 429 failover (<50ms).
FIREBASE_API_KEY	Public (Client Config)	Public client initialization key injected server-side into Jinja templates.
GUEST_SECRET_KEY	Secret (Vault)	Server-side secret used to sign and verify ephemeral HMAC guest session tokens.

---

6. Deployment & Build Process #

Deployment is managed through Vercel via continuous integration from a connected GitHub repository.

• Serverless Setup: vercel.json configures Vercel to build the Python environment. It defines app.py as the source file and specifies the @vercel/python runtime.
• Routing Map: vercel.json rewrites all routes /(.*) to the app.py entrypoint.
• Dependencies: Vercel automatically installs the Python packages listed in requirements.txt and caches the environment for faster cold starts.

// vercel.json
{
  "version": 2,
  "builds": [
    { "src": "app.py", "use": "@vercel/python" }
  ],
  "routes": [
    { "src": "/(.*)", "dest": "app.py" }
  ]
}

---

7. Third-Party Integrations #

• Google Gemini (v1.72.0): Primary high-reasoning engine (gemini-3.6-flash). Employs thread-safe atomic round-robin dispatch across a multi-key pool with a 1.2-second speculative TTFT window before initiating Groq fallback.
• Groq (v1.1.2): Ultra-low latency inference engine (openai/gpt-oss-120b). Operates a multi-key round-robin client pool with active in-flight HTTP 429 failover (<50ms) to guarantee continuous streaming availability.
• Firebase (v11.0.1 Unified): Client-side authentication and NoSQL data persistence (Firestore) for user profiles, verified knowledge, and conversation logs.
• ESPN API & Daemon Sports Cache: Public sports API (site.api.espn.com) polled asynchronously in a background daemon thread (pre-warmed at module startup) to ensure <1ms zero-blocking match context retrieval.

---

8. Technical Constraints & Dependencies #

• Serverless Execution & Streaming TTFT Budget: Vercel serverless environments enforce a 10-second execution ceiling. This constraint is resolved by Server-Sent Events (SSE) streaming and inverted Groq-first inference: Groq LPU execution delivers sub-250ms TTFT across all user requests, with Google Gemini serving as an automatic zero-downtime failover, keeping all transactions well within runtime limits.
• Concurrency & Pre-Fetch Latency Bound: Multi-threaded parallel pre-fetching via ThreadPoolExecutor(max_workers=3) consolidates Firestore knowledge retrieval, episodic memory logs, and live sports cache into a concurrent <200ms window (down from ~750ms sequentially) without thread starvation.
• Non-Blocking Background Task Isolation: Post-inference operations—including Firestore message audit logging, trigger updates, and learned memory extraction—are executed asynchronously via _bg_executor daemon workers, ensuring 0ms delay on user stream termination.
• Client-Side 60fps Frame Budget: The frontend typewriter engine processes character buffers within a 16.6ms frame budget (60fps), dynamically scaling consumption from 1–3 chars/frame up to 16 chars/frame to guarantee smooth organic animation without UI lag.
• Server-Side Security & Rate Limiting: The /chat backend endpoint validates Firebase Auth ID tokens on every request using google.oauth2.id_token against Google's public signing keys (returning 401 Unauthorized if invalid or missing) and throttles requests using an in-memory sliding-window limiter (max 15 requests/minute per UID/IP, returning 429 Too Many Requests). LLM control tags are validated and processed server-side before response sanitization.
• Library Versioning (Resolved & Unified): The codebase has unified all Firebase JS SDK imports to v11.0.1 across both HTML templates (base.html, chat.html, login.html) and JavaScript modules (chatbot.js). This eliminates duplicate SDK singleton instances, optimizes bundle caching, and prevents future deprecation conflicts.