CareerGPT System Architecture: High-Level Components

---

1. User/Client Layer

• Web UI (React, static HTML/JS, etc.)

• API consumers (curl, scripts, automations)

2. API Gateway / Backend Service

• Flask App

  • Receives API calls from UI or scripts

  • Authenticates users (future: JWT, API keys)

  • Handles routing

3. Core Logic / Agent

• Routing Agent

  • Decides which LLM to call (OpenAI or Ollama/local)

  • Controls workflow: “scrape first”, “summarize”, “enrich”, etc.

• Prompt Templates/Workflows

• LLM Adapter Layer

  • Calls out to OpenAI API or local Ollama

  • Standardizes the API contract for all LLMs

4. Data Ingestion

• Screen/Web Scraping Agent

  • Collects job posts or resume data (BeautifulSoup, Playwright, etc.)

  • Cleans, de-duplicates, normalizes raw HTML/text

• Data Pipeline

  • (Optional) ETL jobs, e.g. store in SQLite/Postgres/ChromaDB

  • Keeps a queue/log of scraped sessions and LLM outputs

5. Data Storage

• Config (YAML) File

  • Stores runtime settings, model routing rules, credentials (not in git)

• Database / Embedding Store

  • Stores raw and processed data, user profiles, job meta, etc.

6. Analytics & Visualization

• Logs endpoint/UI (already built!)

• Results Viewer

  • View job market stats, LLM answers, trends

• Admin Dashboard

  • Usage stats, logs, error reports

7. Extensibility

• Switch between LLMs

  • Environment/config switch: OpenAI vs Ollama

  • Future: add more adapters for e.g. Anthropic, Mistral, etc.

---

Diagram (Textual Version/Block Diagram)

I’ll use an ASCII-style block diagram for clarity (but I can render a full PNG if you want):

                [User / Web UI / API Client]
                          |
                          v
    +---------------------------------------------------+
    |        Flask/FastAPI Backend (API Gateway)        |
    |   - Auth / Logging / Routing / Config             |
    +------------------+----------------+---------------+
                       |                |
                       v                v
       [Scraping Agent]             [Analyze Agent/LLM Router]
          |                              |
          v                              |
    [Job/Resume Raw Data]                |
          |                              |
          +---------+--------------------+
                    |
         [LLM Adapter Layer / Prompt Factory]
                    |
        +-----------------------------+
        |      Choose Model:          |
        |  [OpenAI]   OR   [Ollama]   |
        +-----------------------------+
                    |
           [LLM Output (Structured)]
                    |
     +--------------+---------------+
     |      Data Pipeline / DB      |
     +--------------+---------------+
                    |
         [Visualization & Analytics]
                    |
              [Admin Logs UI]

---

Key Features/Highlights

• Switchable LLM backend:

  • Config setting decides which LLM to use.

• Pluggable scraping/data agents:

  • Easily add more sources (e.g., LinkedIn, Indeed).

• Central logging, visualization, and error monitoring.

---

How to Evolve This

• Add event triggers (e.g., run pipeline nightly, on user submit, or webhooks)

• More robust queue/batch processing for scraping/LLM (e.g., Celery, Redis queue, etc.)

• Scalable storage (Postgres/ChromaDB)

---

Next Step

• I can render this diagram as a PNG/flowchart (Mermaid, Lucidchart, draw.io, etc.)

• Just tell me: What style do you want for the image (boxes/arrows, mind map, etc.)?

---

Step-by-Step Implementation Plan

---

Step 1 – Foundation: Identity Backend

Goal:
Provide a service that creates/stores user identity, manages states, and issues JWT after verification.

Tasks:

1. Set up Flask app (identity-backend)
   
   

• Single purpose: identity, FSM, JWT issuance.
  
  

• SQLite for user persistence.
  
  

Create User Table (FSM ready)

CREATE TABLE users (

    id TEXT PRIMARY KEY,

    email TEXT,

    state TEXT NOT NULL DEFAULT 'guest',

    verification_code TEXT,

    user_agent TEXT,

    ip_address TEXT,

    first_seen TIMESTAMP DEFAULT CURRENT_TIMESTAMP,

    last_seen TIMESTAMP DEFAULT CURRENT_TIMESTAMP

);

2. 
   

3. Endpoints:
   
   

• POST /auth/guest: Create guest + set cookie
  
  

• POST /auth/email: Save email, send code → move to email_collected
  
  

• POST /auth/verify: Verify code → issue JWT (state = verified)
  
  

• GET /auth/state: Returns current state for debugging (optional)
  
  

---

---

Step 2 – Guest Flow (First Visit)

Goal:
When a user hits demo.html, detect if they are new → create guest identity.

Tasks:

1. Frontend check (demo.html JS):
   
   

• On load → check if identity_id cookie exists.
  
  

• If not → call /auth/guest (identity-backend).
  
  

2. Identity-backend /auth/guest:
   
   

• Generate UUID.
  
  

• Insert into SQLite with state = guest.
  
  

• Set identity_id cookie (HttpOnly).
  
  

• Return JSON {state: "guest"}.
  
  

---

---

Step 3 – Rule Enforcement (Guest Limit)

Goal:
Allow one free action for guests, then prompt email.

Tasks:

1. careergpt-backend checks state:
   
   

• On each API call, read identity_id cookie (or JWT if available).
  
  

• Call identity-backend /auth/state to confirm state.
  
  

2. Enforce rule:
   
   

• guest → allow first request, mark used (update last_seen or add guest_used = 1).
  
  

• Next request → prompt for email.
  
  

---

---

Step 4 – Email Collection (guest → email_collected)

Goal:
Upgrade identity to store email + start verification.

Tasks:

1. Frontend: Show email prompt → POST /auth/email.
   
   

2. Identity-backend:
   
   

• Save email.
  
  

• Generate 6-digit code (store in verification_code).
  
  

• Send (stub: log code to console).
  
  

• Update state → email_collected.
  
  

---

---

Step 5 – Verification (email_collected → verified)

Goal:
Confirm code and issue JWT.

Tasks:

1. Frontend: Submit code → POST /auth/verify.
   
   

2. Identity-backend:
   
   

• Validate code against DB.
  
  

• Update state → verified.
  
  

Issue JWT with:

{

  "sub": "<user_id>",

  "state": "verified",

  "aud": "careergpt",

  "exp": "<1h>"

}

• 
  

3. Return JWT to frontend (store in localStorage).
   
   

---

---

Step 6 – Protected API Calls (JWT)

Goal:
Use JWT for all future calls to careergpt-backend.

Tasks:

1. Frontend:
   
   

• Attach JWT in Authorization: Bearer <token> header.
  
  

2. careergpt-backend:
   
   

• Middleware validates JWT (shared secret).
  
  

• Enforce state or role before protected routes.
  
  

---

---

Step 7 – Member Upgrade (Future)

Goal:
Support extra FSM step (verified → member) for payments, etc.

---

---

Diagram (Summarized)

User -> demo.html (frontend)

   |

   | 1. On load: check cookie, call /auth/guest if missing

   v

identity-backend (FSM)

   - SQLite (state = guest)

   - Sets cookie identity_id

   |

   | 2. First request → allow guest, mark used

   | 3. Next → prompt email, call /auth/email → email_collected

   | 4. User submits code → /auth/verify → verified + JWT

   |

   | 5. Future requests → careergpt-backend with JWT

   v

careergpt-backend (Protected routes)

   - Validates JWT

   - Enforces rules/roles

---

Immediate Next Step (Implementation)

Do you want me to:

1. Write the actual Flask code for /auth/guest (create identity + set cookie)?
   
   

2. Then integrate frontend JS for checking/creating guest identity?
   
   

3. Then proceed step by step (email collection, verification, JWT)?
   
   

And should we keep mocking the DB for first iteration (in-memory dict) or start directly with SQLite schema + helpers (ready for cPanel deployment)?