CareerForge
Info Portal

Table of Contents

• 01What is CareerForge?
• 02The Four Portals
• 03System Architecture
• 04Backend Services
• 05Authentication & SSO
• 06Data Flow
• 07Employee Portal Manual
• 08Coach Portal Manual
• 09Manager Portal Manual
• 10Admin Portal Manual
• 11Forms & Commitments
• 12AI Mechanics
• 13API Reference
• 14Users & Roles Directory
• 15Access Credentials
• AIAI Deep Dive — Architecture, Guardrails & Roadmap

What is CareerForge?

CareerForge is an internal career development platform for a software IT outsourcing company with eight engineering practices. It connects employees, coaches, and practice managers in a structured, data-driven growth workflow — from skill assessment through structured commitments to verified sign-off.

Key Concepts

• Pseudo-ID — a privacy-preserving identifier derived from Keycloak's sub via HMAC-SHA256. Format: EMP-XXXXX. PII is encrypted at rest (AES-256-GCM); the pseudo-id is the only identifier visible to managers and coaches without explicit employee consent.
• IDP Form — Individual Development Plan created by a coach, committed by the employee, signed off by both coach and manager.
• 1-on-1 Form — Regular meeting summary created by the coach, committed to by the employee.
• Commitment — A formal record of the employee's acceptance of a form. Required before sign-off workflow begins.
• Practice — An engineering discipline (Frontend, Backend, Cloud & DevOps, Data, ML/AI, Mobile, QA, Security). Each practice has one Practice Manager and is served by one or more Coaches.
• Opportunity — A growth opportunity that employees can discover and apply to. Coaches publish skill-development opportunities; managers publish project, bench, L&D, and R&D opportunities.
• Opportunity Match Score — A 0–100% figure computed by the AI Workflow engine showing how well an employee's skills overlap with an opportunity's requirements. Displayed as a colour-coded badge: green ≥70%, yellow 40–69%, grey <40%.
• AI Workflow Config — An admin-managed record that defines which AI provider/model drives all suggestions across all portals. Only one config is active at a time. Each feature (role suggestions, coaching advice, mentor matching, etc.) has its own TTL, guardrails, and optional model override. The active config can point to a cloud provider or a self-hosted LLM (Ollama, LM Studio, vLLM).
• Mentor Matcher — Algorithm in the Coach portal that scores mentors against an employee: 55% skill coverage overlap, 30% seniority fit (gap ≤ 2 ideal), 15% current assignment load. Filters to mentors who are available and at equal or higher seniority.

The Four Portals

CareerForge is delivered as four separate single-page applications, each scoped to one user role, with independent authentication.

System Architecture

CareerForge follows a microservices architecture deployed on Kubernetes. Each portal has a dedicated backend API service; a shared PostgreSQL database holds canonical state; Redis provides caching and session storage.

Backend Services

Each FastAPI service owns a bounded domain. Services share the same PostgreSQL database but access only their own tables.

{
  "employee": {
    "role_suggestions":       { "enabled": true, "ttl_hours": 24, "guardrails": { "max_roles": 5, "min_match_score": 0.3 }, "model_override": null },
    "learning_path":          { "enabled": true, "ttl_hours": 48, "guardrails": { "max_nodes": 12, "include_certs": true }, "model_override": null },
    "opportunities_matching": { "enabled": true, "ttl_hours": 6, ... },
    "ai_chat":                { "enabled": true, "ttl_hours": 1, ... }
  },
  "coach": {
    "coaching_advice":   { "enabled": true, "ttl_hours": 4, "guardrails": { "require_pseudo_id": true, "safe_mode": true }, ... },
    "market_intelligence": { "enabled": true, "ttl_hours": 6, ... },
    "mentor_matching":   { "enabled": true, "ttl_hours": 24, "guardrails": { "min_match_score": 0.2, "max_mentors": 5 }, ... }
  },
  "manager": {
    "team_readiness":         { "enabled": true, "ttl_hours": 24, "guardrails": { "show_names": false }, ... },
    "opportunities_ai_match": { "enabled": true, "ttl_hours": 2, "guardrails": { "max_candidates": 10, "min_match_score": 0.3 }, ... }
  }
}

Authentication & SSO

All portals use OpenID Connect with PKCE (Proof Key for Code Exchange). No passwords are stored by CareerForge — credentials live in Keycloak.

Keycloak Realms

Manager Role Check

The Manager Portal uses the employee realm but additionally requires the manager realm role to be present in the JWT. If the user authenticates successfully but lacks this role, they are redirected to /access-denied.

OIDC PKCE Flow

PII Privacy Model

Employee personally identifiable information (full name, email, phone) is stored encrypted with AES-256-GCM. The encryption key is derived per-employee and stored in a secrets manager.

Coaches and managers see only pseudo-ids by default. To reveal PII, the employee must explicitly approve a PII reveal request — a push notification is sent, and on approval a short-lived consent token is issued. The requesting party redeems the token to temporarily decrypt the profile.

Data Flow

Opportunity & Application Flow

Form Sign-off Flow

Manager Opportunity & AI Match Flow

Pseudo-ID Derivation

Each employee's identifier is derived deterministically from their Keycloak sub (UUID) using HMAC-SHA256 + Base32:

HMAC_KEY = bytes.fromhex("77b1c3ed6d3a24931aef148f4099eabc355c79de084f5c10701d5de6044d16f0")

def derive_pseudo_id(keycloak_sub: str) -> str:
    digest = hmac.new(key=HMAC_KEY, msg=sub.encode(), digestmod=hashlib.sha256).digest()
    encoded = base64.b32encode(digest[:4]).decode("ascii")[:5]
    return f"EMP-{encoded}"

This means pseudo-ids are stable (same sub → same id), reversible only by someone with the HMAC key, and safe to expose to coaches and managers.

Employee Portal Manual

The Employee Portal at demo.lupulup.com is your personal career development hub. Sign in with your company SSO credentials (employee realm).

Dashboard

The dashboard shows your current readiness score (0–100), recent activity, skill heatmap, and quick links to pending actions. The readiness score is computed from your skills, certifications, education, learning history, and engagement.

My Profile

• View your current role, seniority, specialisation, and experience years.
• Your Pseudo-ID is displayed — this is how coaches and managers identify you in their portals.
• PII (name, email, contact) is hidden by default. To share it temporarily with a coach or manager, they submit a PII reveal request and you approve it from a push notification.
• Update career goals, learning style preference, and mentoring availability.

Skills & Heatmap

• Browse your skill inventory — each skill has a proficiency level (beginner → expert) and a last-validated date.
• The heatmap shows coverage across technical domains, highlighting gaps relative to your seniority benchmark.
• Earn skill validation by completing courses, certifications, or coach-verified IDP milestones.

Opportunities

• Browse open opportunities posted by coaches and managers — project rotations, bench assignments, certification sponsorships, L&D programmes, R&D initiatives, speaking slots, and mentoring assignments.
• Each opportunity shows a Match Score badge computed from your skill profile vs the opportunity's required skills: ≥70% (strong match) · 40–69% (partial) · <40% (low)
• Filter by specialisation, seniority, type, and tags.
• Apply with a cover note. You can track application status (pending → accepted / rejected) under My Applications.
• Withdraw a pending application at any time.

My Forms

• View all forms addressed to you (IDP, 1-on-1, nomination, performance review).
• A form in pending_commitment status requires your action — read the content and click Commit to accept the goals.
• Once committed, the form moves through coach sign-off → manager sign-off → ACTIVE.
• Active forms are your live commitments. Check milestones and update progress.

AI Advice

• Ask the AI coach for personalised guidance — career path options, skill gap recommendations, learning resource suggestions.
• The AI uses your anonymised profile (no PII). You can provide extra context in free text.
• Save useful advice snippets to your profile notes.

Notifications

• Receive in-app notifications for: new form assignments, application decisions, PII reveal requests, form sign-off completions.
• Approve or deny PII reveal requests directly from the notification panel.

Coach Portal Manual

The Coach Portal at demo-coach.lupulup.com is your workspace for managing employee development. Sign in with your coach realm credentials.

Dashboard

Overview of your active opportunities, pending applications, forms awaiting your sign-off, and cohort readiness trends.

Opportunities

Forms

Creating a Form

Select form type, target employee pseudo-id, and optionally assign a practice manager. Form types:

• IDP — Individual Development Plan. Full goals, milestones, timeline, skills targeted.
• One-on-One — Meeting summary. Discussion topics, action items, follow-up date.
• Nomination — Recommend an employee for a role, award, or programme.
• Performance Review — Structured 360° review with ratings and narrative.

After creation, the form status is pending_commitment — waiting for the employee to commit.

Sign-off

Once the employee commits, the form appears in your Sign-off Queue. Review the commitment, add coach notes, and sign. The form then moves to the manager for final sign-off (if a manager is assigned).

Mentor Matcher

On any employee's detail page, the Mentor Match card shows the top-N mentors best suited to that employee — ranked by a weighted score:

• 55% — Skill coverage: fraction of the employee's skills covered by the mentor's skill set.
• 30% — Seniority fit: gap of 0–2 levels scores full marks; each extra level deducts 0.15.
• 15% — Load: mentors with fewer active assignments score higher.

Mentors are only considered if they have available_for_mentoring = true and are at equal or higher seniority than the employee. Match scores are colour-coded: green ≥70%, yellow 40–69%, grey <40%.

AI Coaching Advice

On an employee's detail page, enter a coaching question — the AI receives a strictly-grounded context (the anonymised profile, top-matched opportunities, Industry 4.0 readiness snapshot, and the active company strategy) and returns auditable advice. The system prompt forbids any invented education, certifications, or metrics; Perplexity-style citation markers and raw UUIDs are scrubbed. Every call is logged in the AI suggestion audit trail with a context_used breakdown showing which pillars actually fed the answer. Users can mark each suggestion accepted / dismissed / rated 1–5 via POST /api/v1/ai-suggestions/{log_id}/feedback; admins see acceptance rate and average rating per suggestion_type at /api/v1/admin/ai-workflow/audit/feedback-summary. The TTL and guardrails for coaching advice are configurable per-feature in the Admin → AI Workflow Connector.

Analytics

• Skill Heatmap — coverage and gaps across your coaching cohort.
• Applications Pipeline — funnel view from applied to placed.
• Cohort Readiness — average and distribution of readiness scores.
• Opportunity Performance — fill rate, time-to-fill, application volume.

Manager Portal Manual

The Manager Portal at demo-manager.lupulup.com gives Practice Managers visibility into their team's career progression. Requires the manager Keycloak role.

Dashboard

Summary of your team: total members, average readiness score, pending sign-offs, active IDPs, and recent form activity.

My Team

• List of all employees where your pseudo-id is their line_manager_pseudo_id.
• Each row shows pseudo-id, seniority, specialisation, readiness score, and active form count.
• Click a team member to see their full profile: skill breakdown, active forms, readiness score components, and progression history.
• Team member PII is hidden by default. Submit a reveal request to temporarily view name and contact.

Sign-offs

• Forms appear in your queue after the employee has committed and the coach has signed off.
• Review the full form content, coach notes, and employee commitment.
• Add your manager comments and sign off to mark the form ACTIVE.
• You can request clarification from the coach before signing.

Opportunities

Managers can create and publish opportunities visible to all employees in the Employee Portal.

Practice Managers

Admin Portal Manual

The Admin Portal at demo-admin.lupulup.com is for platform operations. Restricted to users in the admin Keycloak realm.

Skills Taxonomy

• Browse the global skill catalogue — ~200 skills across all engineering practices.
• Add new skills: set name, category, description, and related skills.
• Deprecate obsolete skills — existing proficiency records are preserved but the skill is hidden from new entries.
• Merge duplicate skills: all employee records are remapped.

System Analytics

• Platform-wide KPIs: active users (7d / 30d), forms created, form completion rate, opportunity fill rate.
• Drill down by practice, seniority, or coach.
• Export data as CSV for external reporting.

Audit Log

• Every create / update / delete action is logged with actor pseudo-id, action type, resource, and timestamp.
• Filter by date range, actor, resource type, or action.
• Audit log is append-only — records cannot be modified or deleted through the UI.

ML Model Management

• View current model versions tracked in MLflow.
• Trigger re-training jobs (runs as a Kubernetes Job).
• Promote a model version to production — employee service will use it for readiness scoring.

AI Workflow Connector

Configure which AI engine drives all CareerForge suggestions. Navigate to Connectors → AI Workflow tab.

• Create a config — choose provider (anthropic, openai, perplexity, gemini, self_hosted), model name, and API key. For self-hosted, set the Base URL (e.g. http://ollama:11434) — the connector auto-appends /v1 if needed.
• Activate — only one config is active at a time. Activating one automatically deactivates all others. The active config is cached for 5 minutes across all services.
• Per-feature coverage — expand each feature panel (e.g. role_suggestions, coaching_advice, mentor_matching, opportunities_ai_match) to set:
  • Enabled toggle
  • TTL (hours) — how long a suggestion result is cached before re-generation
  • Model override — use a different model for this feature only
  • Guardrails — key/value pairs (e.g. max_roles: 5, safe_mode: true)
• Suggestion Audit tab — browse the append-only log of every AI call: suggestion type, portal, feature, employee pseudo-id (if applicable), model used, sources used, generated_at, expires_at.

Forms & Commitments

Forms are the core unit of documented career development in CareerForge. Every form goes through a structured lifecycle from creation to full sign-off.

Form Lifecycle

Form Types

Commitment Object

When an employee commits to a form, a FormCommitment record is created:

{
  "form_id": "uuid",
  "employee_pseudo_id": "EMP-XXXXX",
  "status": "committed",          // or: in_progress, completed, abandoned
  "commitment_date": "2026-04-21T10:00:00Z",
  "employee_notes": "I accept and will focus on Kubernetes certification first.",
  "progress_percentage": 0,
  "milestones_completed": 0
}

AI Mechanics

How each AI suggestion is computed across all four portals — what is deterministic versus LLM, the per-feature guardrails it respects, and the audit log entry it produces. Click any row to expand.

API Reference

All services expose OpenAPI docs at /docs (Swagger UI) and /redoc (ReDoc). Base paths are /api/v1.

Users & Roles

Dev environment user directory. The employee realm contains 108 users (employees + managers); the coach realm contains 2 coaches; the admin realm contains 1 administrator. All dev accounts use the password Demo2026!.

Administrators (admin realm)

Coaches (coach realm)

Employees (employee realm)

Access Credentials

Simulation Accounts (all portals)

Container Registry

Kubernetes