Flow Document #

Flows v1.0 · ronilprasad8.tech · Interaction & Data Diagrams

This document visualizes the major user journeys and internal data processes within the application. The diagrams use Mermaid.js to illustrate routing decisions, authentication states, and the multi-layered LLM failover system.

The primary user journey for a public visitor navigating the portfolio. The persistent navigation bar (defined in base.html) and global routing (app.py) control access to different content areas.

graph TD A([Visitor Lands on Site]) --> B[/ GET / : Home View /] B --> C{Navigation Bar} C -->|Clicks 'About'| D[/ GET /about : Bio & Skills /] D --> D1(View Coursework) D --> D2(Download CV /cv) C -->|Clicks 'Projects'| E[/ GET /project : Portfolio /] E --> E1(External Link: Assistant Project) E --> E2(External Link: GitHub Repos) C -->|Clicks 'Contact'| F[/ GET /contact : Social Links /] C -->|Clicks Auth Icon| G[/ GET /login /] B --> H[Global Floating Chat Widget] D --> H E --> H F --> H H --> I{User Authenticated?} I -->|No| J[Display: 'Log in to chat'] I -->|Yes| K[Enable Chat Input]

Step-by-Step Breakdown:

  1. Entry Point: User hits the / route. app.py renders templates/index.html.
  2. Persistent UI: The navigation bar and floating chat widget (controlled by chatbot.js) persist across views.
  3. Exploration: The user browses static views (/about, /project, /contact).
  4. Chat Attempt: The user clicks the floating widget. chatbot.js verifies onAuthStateChanged. If null, the UI is blocked with a login prompt.

2. Authentication Flow #

The process by which a user registers, logs in, or resets their password. All authentication is client-side, managed by Firebase Auth and implemented in login.html.

graph TD Start([User navigates to /login]) --> Tabs{Select Action} Tabs -->|Login Tab| L1[Enter Email & Password] L1 --> L2{signInWithEmailAndPassword} L2 -->|Success| L3[Redirect to /] L2 -->|Error| L4[Show Error Banner] Tabs -->|Sign Up Tab| S1[Enter Details & Validate Rules] S1 --> S2{createUserWithEmailAndPassword} S2 -->|Error| S3[Show Error Banner] S2 -->|Success| S4[Write profile to Firestore 'users'] S4 --> S5[Redirect to /] Tabs -->|Google Button| G1{signInWithPopup} G1 -->|Success| G2{Is First Time?} G2 -->|Yes| G3[Write profile to Firestore 'users'] G2 -->|No| G4[Redirect to /] G3 --> G4 G1 -->|Error| G5[Show Error Banner] Tabs -->|Forgot Password| F1[Enter Email] F1 --> F2{sendPasswordResetEmail} F2 -->|Success| F3[Show Success Banner + Spam Notice] F2 -->|Error| F4[Show Error Banner] F3 --> L1

Step-by-Step Breakdown:

  1. UI Selection: User selects Login, Sign Up, or clicks "Forgot Password?" (controlled via DOM class toggling in login.html).
  2. Validation: Client-side JS validates inputs (e.g., regex matching for 8+ characters, symbols, and numbers).
  3. Firebase Auth: Calls the respective Firebase v10 SDK method.
  4. Firestore Profile: On new registration (Email or Google), a document is created in the users/{uid} collection with the user's name and email.
  5. State Change: Once authenticated, onAuthStateChanged fires globally across the app (in base.html and chatbot.js), unlocking protected elements.

3. AI Chatbot Data & Failover Flow #

The core technical pipeline of the application. This flow details how user messages are augmented with live context, routed to appropriate LLMs, and how system knowledge is extracted and saved.

graph TD Client1([User submits message]) --> Client2[chatbot.js packages History + User Info] Client2 --> HTTP[POST /chat JSON Payload] HTTP --> Server1[app.py: /chat Route] Server1 --> Engine[chatbot.py: generate_goat_response] Engine --> Context1{Fetch Live Context} Context1 --> |Get Time| Time(Fiji Time & Activity) Context1 --> |Get Match| ESPN(ESPN API: Bayern Match) Time --> Prompt[Inject into System Prompt] ESPN --> Prompt Prompt --> Intent{Intent Classification} Intent -->|Keywords Match Personal| LLM_Gemini{Gemini Try Key 1} Intent -->|Keywords Match General| LLM_Groq{Groq (Llama 3.3)} LLM_Gemini -->|Success| Out[Format Response] LLM_Gemini -->|429/Error| LLM_Gemini2{Gemini Try Key 2} LLM_Gemini2 -->|Success| Out LLM_Gemini2 -->|Error| LLM_Groq LLM_Groq -->|Success| Out LLM_Groq -->|Error| Dead[Return Deadlock Error String] Out --> HTTPS_Out[Return JSON to Client] Dead --> HTTPS_Out HTTPS_Out --> PostProc{JS Regex Parse} PostProc -->|Finds LEARN tag| FS1[Save Fact to Firestore 'knowledge'] PostProc -->|Finds SAVE tag| FS2[Save Log to Firestore 'messages'] PostProc --> UI[Render Typewriter Effect] FS1 --> UI FS2 --> UI

Step-by-Step Breakdown:

  1. Client Payload: chatbot.js captures the message, user's first name, email (to check if they are the Owner), and previous conversation history.
  2. Live Context Gathering: chatbot.py determines the current time in Fiji and deduces a likely activity (e.g., "At USP"). It also makes a synchronous request to the ESPN API (with a 3-second timeout) for recent sports scores.
  3. Intent Routing: The engine checks the user's message against a list of ~50 keywords (e.g., "ronil", "usp", "tech stack"). If matched, it routes to Gemini; otherwise, it sends the request straight to Groq.
  4. Failover (L1/L2/L3): If Gemini Key 1 hits a rate limit, the system automatically tries Key 2. If both fail, it falls back to Groq.
  5. Extraction Engine: Upon receiving the text, client-side JS scans for specific instruction strings like [LEARN_RONIL: ...] or [SAVE_TRIGGER: ...].
  6. Persistence: Detected facts are pushed to Firestore (using setDoc/arrayUnion), then the tags are stripped from the text before it is animated onto the screen.