MyCVPath — AI-Native CV Intelligence Platform

Execution Protocol

1. Defined 6 specialized agents in pipeline order: CV_PARSER (raw text → structured CV JSON), CV_VALIDATOR (enrichment + gap filling), JOB_PARSER (JD text → structured requirements), JOB_ANALYZER (gap analysis + match scoring), CV_TAILOR (CV rewrite targeting specific JD), COMPARATIVE_SCORER (tailored CV vs JD quality score)
2. Implemented PromptBuilder abstraction that assembles system prompt + per-agent JSON schema + TOON-serialized user context — schema is dynamically injected into the prompt body to force structured output without relying on provider-specific JSON mode features
3. Built TOON Serialization Layer converting complex nested Go structs (CV data, job requirements, analysis) into flattened LLM-optimized prompt encoding — avoids token-expensive JSON nesting while preserving all semantic relationships
4. Designed provider chain resolution from JSONB config (stored in user_model_profiles or default_model_config): sequential failover tries each provider/model in order with exponential backoff — if OpenAI fails, falls back to Anthropic, then Gemini, then OpenRouter
5. Implemented multi-provider client factory supporting OpenAI-compatible API format, Anthropic Messages API, and Google Gemini API — single orchestrator interface with provider-specific serialization per client
6. Built BYOK key resolution path: for BYOK-tier users, AES-256-GCM encrypted key is fetched from user_model_profiles, decrypted in memory at request time, injected into provider client — key never written to logs
7. Governance middleware checks request eligibility before agent execution: verifies daily quota (free tier), checks monthly spend cap (paid tier), validates BYOK subscription status — rejects with structured error if any limit exceeded
8. Persisted every LLM request to analytics_monitoring.llm_generation_logs with full request/response JSONB, token counts, estimated_cost_usd, duration_ms, provider, model, agent_type, and status (success/error/timeout)
9. Admin handlers expose /api/admin/llm-analytics endpoint aggregating logs by provider/model over configurable date windows — used by admin-service dashboard for cost visibility
10. Global free mode toggle in platform_settings.global_free_mode bypasses all quota and billing checks when enabled — allows platform-wide open access during promotions or testing without per-user config changes
11. CLI tooling (cmd/cli.go) enables local agent testing without HTTP round-trip — same orchestrator code path, different transport layer — verified agent outputs against expected JSON schemas before deployment

Execution Protocol

1. Built modular section element system in ReportLab: each CV section (Summary, Experience, Education, Skills, Projects, Certifications, Languages) implemented as an independent class with controlled spacing, font weights, and bullet formatting — assembled via section-level flow objects
2. Implemented V1 Legacy Engine with fixed schema: section ordering hardcoded, deterministic layout guarantees exact pixel-level repeatability for the same input — used for regression testing and backwards compatibility
3. Implemented V2 Dynamic Engine with flexible section ordering: sections defined as ordered list in input JSON — CV_TAILOR agent output controls which sections appear and in what order for maximum relevance to the target job
4. Loaded EB Garamond font family (Regular, Medium, Bold, ExtraBold, Italic, BoldItalic, MediumItalic, ExtraBoldItalic) as custom ReportLab fonts — editorial serif typography for professional ATS-parseable output that passes both human and automated screening
5. ATS optimization constraints enforced in layout: no multi-column text flows, no text boxes over images, no decorative lines interrupting paragraph flows, all section headers as plain bold text — ensures standard PDF text extraction by ATS parsers
6. PDF text extraction endpoint /extract-text: PyPDF2 reads uploaded binary PDF, extracts raw text preserving paragraph breaks, returns as string to go-llms for CV_PARSER agent input — initial ingestion step of the full pipeline
7. Cover letter generation support: /generate-pdf accepts cover_letter field alongside CV JSON — generates combined PDF or separate DOCX cover letter depending on output_mode flag
8. ThreadedConnectionPool manages concurrent PDF generation requests without blocking — each thread handles one generation job independently with isolated ReportLab canvas state
9. Error forwarding to analytics service: any generation failure POST-fires to analytics-monitoring /track/error endpoint asynchronously — caller receives error response immediately, error is logged in background
10. Health check endpoints /health (liveness) and /health/db (PostgreSQL connectivity) used by Docker Compose dependency management and production monitoring

Execution Protocol

1. Axum HTTP router with Tower middleware stack: CORS for cross-service requests, request tracing via Tower Trace for structured log output, error handling middleware converting Rust errors to HTTP 500 responses
2. All write operations wrapped in tokio::spawn: every POST to /track/* immediately returns 202 Accepted, then executes the database write on a spawned async task — caller experiences <1ms handler overhead regardless of database load
3. Page view tracking (/track/page-view): captures path, referrer, duration_ms, session_id, user_id/guest_id, device_type, browser — persisted to analytics_monitoring.page_views
4. User action tracking (/track/action): captures interaction metadata (action_type, element_id, metadata JSONB) — enables behavioral funnel analysis for UX optimization
5. LLM request monitoring (/track/llm-request): receives token counts, cost, latency, provider, model, agent_type, status from go-llms after each generation — persisted to llm_generation_logs with full request/response JSONB when debug mode enabled
6. Error ingestion (/track/error): centralizes errors from all 5 microservices — captures microservice origin, file_path, line_number, function_name, error_type, severity (error/warning), stack_trace, request_context JSONB, resolution status (new/investigating/resolved/ignored)
7. Hourly aggregation into user_model_usage: Tokio background task computes sum(prompt_tokens), sum(completion_tokens), sum(estimated_cost_usd) per user+model+provider+hour — admin dashboard queries this table for cost reporting
8. Session fingerprinting in visitor_sessions: correlates authenticated user_id, guest_id, and anonymous visitor across page views — enables conversion funnel analysis from first visit through registration
9. Statistics endpoints (/stats/overview, /stats/llm-usage, /stats/user-activity) perform aggregated SQL queries with configurable time windows — consumed by admin-service Node.js dashboard
10. pattern_insights table receives ML-driven pattern updates via stored procedure: job types, company categories, and success correlations learned over time from comparative_scorer outputs

Execution Protocol

1. Schema separation enforced at migration level: 01_init.sql creates both schemas and installs pgcrypto extension — all subsequent migrations target specific schema with fully-qualified table names (public.users, analytics_monitoring.visitor_sessions)
2. Identity layer (02_identity.sql): users table with email verification state, guest_users with migration_status and migrated_at tracking, sessions with device_info/ip_address/is_revoked, user_model_profiles with provider_chain JSONB and AES-encrypted api_key_encrypted bytea field
3. CV and jobs layer (03_cv_and_jobs.sql): master_cvs with version_number, content_hash (MD5/SHA256 dedup), growth_history JSONB, and created_for_job_id foreign key — each job_applications row captures full workflow funnel state (workflow_step, reached_import/job/tailor/complete booleans, abandonment_reason, timing metrics in milliseconds)
4. Pipeline state layer (04_workflow_and_drafts.sql): import_data/job_data/tailor_data as 1:1 companions to job_applications — tailor_data stores immutable input snapshots (master_cv_snapshot JSONB, job_data_snapshot JSONB, analysis_snapshot JSONB) enabling full reproducibility of any tailoring run
5. Analytics schema (05_analytics_and_monitoring.sql): full telemetry infrastructure including llm_generation_logs with model parameters JSONB, full_request/full_response JSONB debug fields, token counts, estimated_cost_usd, duration_ms, started_at/completed_at timestamps
6. Logic layer (06_logic.sql): stored procedure migrate_guest_to_user() executes full account conversion — copies CVs, job applications, sessions from guest namespace to user namespace, handles singleton table collisions (app_sessions, builder_states, user_preferences) by keeping newer timestamp, merges user_model_usage by summing tokens/cost for matching hour+model+provider windows, all in single ACID transaction
7. Migrations 07–17 add: billing tables (user_accounts with balance/spending/currency), platform_settings (global_free_mode toggle, service fees, minimum balances), default_model_config JSONB for system-wide provider chains, interview_steps tracking, generation_requests queue with pending/processing/completed states
8. Connection pooling per service: application (Next.js pg pool), go-llms (Go database/sql pool), cv-manipulation (Python ThreadedConnectionPool), analytics-monitoring (Rust deadpool-postgres), admin-service (Node.js pg pool) — each service sized independently
9. Query optimization via targeted indexes: job_applications indexed on (user_id, workflow_step), llm_generation_logs indexed on (user_id, created_at), user_model_usage indexed on (user_id, model, hour_bucket) — covers all dashboard aggregation patterns
10. JSONB provider chains enable zero-migration provider config updates: changing a user's provider chain requires only an UPDATE to user_model_profiles.provider_chain — no schema migration, no service restart

Execution Protocol

1. React Context maintains workflow state in memory: currentJob, importData (parsed CV JSON), jobData (analyzed job requirements), tailorData (tailored CV + cover letter) — each state slice matches the corresponding database table schema exactly
2. LocalStorage sync layer serializes Context state to localStorage after every agent response completion — if browser crashes mid-session, page reload restores from localStorage before initiating database fetch
3. Dual-trigger synchronization: (1) after each agent pipeline step completes, application POSTs the step result to its corresponding API route (import_data, job_data, tailor_data) for DB persistence; (2) on Next.js router navigation events, a sync effect flushes any pending context state to DB
4. API routes proxy agent calls to go-llms: /api/agent/[agentname] receives the pipeline step payload, forwards to go-llms service with internal network address, streams response back to client — Next.js acts as BFF (Backend-for-Frontend) isolating the client from internal service addresses
5. Guest session flow: unauthenticated users assigned guest_id stored in cookie — all workflow state persisted under guest_users and guest-namespaced pipeline tables — full session preserved across browser sessions until registration or expiry
6. Guest-to-user migration triggered on registration: application calls /api/auth/register which invokes migrate_guest_to_user() in a single database transaction — all guest CVs, job applications, and pipeline state transferred atomically to new user account
7. Singleton table collision logic in migration: if both guest and new user have an app_sessions row, the one with the newer updated_at timestamp wins — prevents data loss in edge case where user had used the platform previously under a different guest session
8. Job application workflow funnel tracking: each transition between workflow steps (import → job → tailor → complete) updates reached_* boolean flags and records timing in milliseconds — abandonment detection fires on navigation away from incomplete workflow
9. Versioned Master CV model: master_cvs table stores the user's canonical CV with version_number increment on each update — job applications reference the master CV version at time of creation via created_for_job_id — ensures the tailored output can always be traced back to the exact input state
10. Builder state persistence: cv-builder UI state (section visibility, ordering preferences, custom entries) persisted in builder_states table — survives page reloads and multi-device access

Execution Protocol

1. FREE tier: default provider chain from platform_settings applied to all requests — default_model_config stores system-wide agent configurations in JSONB — daily request quota enforced (default: 5/day) via counter in user_model_profiles.daily_requests_used, reset at midnight UTC
2. PAID tier: user pre-loads balance via payment flow — go-llms deducts estimated_cost_usd from user_accounts.balance after each successful generation — service fee (default: 20% margin) added to raw provider cost — minimum balance gate checked before agent execution
3. BYOK tier: user pastes their own OpenAI/Anthropic/Gemini API key in platform UI — application encrypts key with AES-256-GCM before PostgreSQL write — encryption key stored in environment variable, never in database — decryption occurs in go-llms memory at request time only
4. AES-256-GCM implementation: random 12-byte nonce generated per key, prepended to ciphertext in api_key_encrypted bytea field — decryption verifies authentication tag before use — encrypted key never appears in logs even at DEBUG level
5. Rate limiting enforcement: per-user daily_limit and hourly_limit fields in user_model_profiles — go-llms checks both limits before agent execution — limits configurable per user by admin without code deploy
6. Monthly spend cap: user_model_profiles.monthly_spend_limit and spending_reset_date enable per-user spending guardrails — aggregated from user_model_usage table which accumulates hourly — go-llms checks current_month_spend < monthly_spend_limit before execution
7. Global free mode: platform_settings.global_free_mode boolean bypasses ALL quota and billing checks when true — enables full platform access during promotional periods or incident recovery — toggled via admin-service API without service restart
8. Cost tracking accuracy: estimated_cost_usd calculated from token counts × published provider pricing rates hardcoded per model in go-llms config — actual vs estimated reconciliation exposed in admin dashboard
9. BYOK subscription lifecycle: subscription_status field (active/inactive/cancelled/expired) in user_model_profiles — inactive/expired subscriptions fall back to FREE tier defaults instead of failing — prevents hard breakage when BYOK key expires
10. Audit trail: every LLM generation creates an immutable llm_generation_logs row — admin can reconstruct exact cost history per user per provider — used for dispute resolution and cost modeling

Execution Protocol

1. postgres service starts first with no dependencies — configured with persistent volume mount for data durability across container restarts — health check waits for pg_isready before declaring healthy
2. migrations service starts as a one-shot container after postgres is healthy — runs all 17 SQL files sequentially via a shell script — exits with code 0 on success, fails the entire compose stack on any migration error — prevents partial schema state
3. analytics-monitoring (Rust) starts after migrations complete — chosen as first application service because all other services fire telemetry events to it — being up early ensures no telemetry is dropped during service startup
4. application (Next.js), go-llms (Go), cv-manipulation (Python), admin-service (Node.js) all start in parallel after analytics-monitoring is healthy — no startup ordering between them (each handles the case where a dependency is temporarily unavailable)
5. Internal app-network: all services communicate via Docker internal DNS (e.g. http://go-llms:7689) — no port exposure to host for internal services — Next.js API routes use internal addresses when proxying to go-llms and cv-manipulation
6. External gateway-public network: only application service connected — Nginx reverse proxy on the host terminates HTTPS and routes to localhost:7687 — single external ingress point
7. All host port bindings use 127.0.0.1 prefix (e.g. 127.0.0.1:7687:7687) — prevents accidental external exposure in cloud environments where all interfaces are reachable — security-first default
8. Memory limits prevent runaway processes: Application 2GB/512MB reservation, Go-LLMs 1GB/256MB, CV-Manipulation 1GB/256MB (ReportLab rendering is CPU/memory intensive for complex CVs), Analytics-Monitoring 512MB/128MB
9. Health check probes per service: Application uses curl /api/health, Go-LLMs and Analytics use wget /health — probes tuned with start_period to avoid false failures during JVM/Go/Rust cold start
10. .env file separation: DATABASE_URL, LLM API keys, admin codes, JWT secrets loaded from environment — no secrets in docker-compose.yml or image layers