Technical Requirements Document #

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

1. System Architecture Overview #

The application uses a serverless, hybrid client-server architecture. The backend is a Python Flask application deployed as a Vercel Serverless Function, responsible for routing and orchestrating external API calls to LLM providers and live data APIs. The frontend utilizes standard HTML/JS templates rendered server-side (Jinja2) but delegates all authentication and database interactions directly to Firebase via client-side JavaScript SDKs.

2. Technology Stack #

Dependency / Tool	Version	Purpose	Source
Flask	3.1.3	Core backend web framework & routing engine.	`requirements.txt`
google-genai	1.72.0	Primary LLM integration for the Gemini AI models.	`requirements.txt`
groq	1.1.2	Secondary (failover) LLM integration for Llama 3.3.	`requirements.txt`
Firebase JS SDK	10.12.0 / 11.0.1	Client-side authentication and Firestore database access.	`templates/` & `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	File Location	Purpose
GET	`/`	`app.py (L30)`	Renders `index.html` (Home Page).
GET	`/about`	`app.py (L34)`	Renders `about.html`.
GET	`/project`	`app.py (L38)`	Renders `project.html`.
GET	`/contact`	`app.py (L42)`	Renders `contact.html`.
GET	`/login`	`app.py (L46)`	Renders `login.html` (Auth flow).
GET	`/architecture`	`app.py (L50)`	Renders `architecture.html`.
GET	`/cv`	`app.py (L54)`	Serves `CV/CV.pdf` file.
GET	`/chat`	`app.py (L59)`	Renders dedicated `chat.html` page.
POST	`/chat`	`app.py (L63)`	Receives JSON payload (message, history, user data). Calls `generate_goat_response()` and returns JSON response.
GET	`/sitemap.xml`	`app.py (L90)`	Serves static `sitemap.xml` for SEO.
GET	`/google[id].html`	`app.py (L17)`	Serves Google Search Console verification string.

5. Environment & Configuration #

The system requires the following environment variables. In local development, these are read via python-dotenv from a .env file. In production, they are configured in the Vercel dashboard.

Variable Name	Description
`GEMINI_API_KEY`	Stores comma-separated keys for the Google Gemini API to enable the L1/L2 Key Rotation failover mechanism.
`GROQ_API_KEY`	Stores the API key for the Groq platform (Llama 3.3 model failover).
`FIREBASE_API_KEY`	The public API key injected server-side into Jinja templates for initializing the Firebase JS SDK on the client.

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): Used as the primary reasoning engine for personalized chat interactions.
Groq (v1.1.2): Used as the secondary inference engine. Due to its Llama 3.3 model and fast TTFT (Time To First Token), it handles general queries and failover routing.
Firebase (v10/v11): Client-side authentication and NoSQL data persistence (Firestore) for user profiles, learned knowledge, and message logs.
ESPN API: A public, undocumented API (site.api.espn.com) polled by the backend to fetch live match results for context injection.

8. Technical Constraints & Dependencies #

Vercel Timeout: The Vercel free tier limits serverless function execution to 10 seconds. AI inference requests that exceed this duration will fail automatically. This necessitates fast TTFT models and short timeouts for external context fetching (e.g., ESPN API has a 3-second hard timeout).
Client-Side Security: The /chat backend endpoint does not validate Firebase Auth tokens on the server. Security relies on client-side UI gating. This implies the API is technically vulnerable to direct POST requests if discovered.
Library Version Conflict: The codebase currently mixes Firebase SDK versions (v10.12.0 in HTML templates and v11.0.1 in JS module imports). While they are functionally compatible for current usage, unifying the library versions is recommended to avoid future deprecation conflicts.