cesnimda
fd9bd3f47a
ai-career-assistant.md (modules, prompt flow, provider abstraction, append-only history model, extension points, security). Master guide + roadmap Phase 5 updated with the shipped workspace and the open provider-selection extension. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
754 lines
9.2 KiB
Markdown
754 lines
9.2 KiB
Markdown
# Jobjakt Master Implementation Guide
|
||
|
||
Version: 1.1
|
||
|
||
---
|
||
|
||
# Purpose Of This Document
|
||
|
||
This document is the primary source of truth for the product *direction*. For the
|
||
*current system* and the *recovered Career Workspace architecture*, read the documents
|
||
linked below — they are verified against the code and take precedence over any stub
|
||
elsewhere in `docs/`.
|
||
|
||
Before making significant changes:
|
||
|
||
1. Read this document (direction and non-negotiables).
|
||
2. Read the relevant linked documentation (below).
|
||
3. Understand existing architecture — verify against the actual codebase.
|
||
4. Make incremental improvements.
|
||
|
||
Do not redesign based on assumptions.
|
||
|
||
Always verify against the actual codebase.
|
||
|
||
---
|
||
|
||
# Source-Of-Truth Documents
|
||
|
||
Read these before touching the areas they cover. Where one disagrees with the code,
|
||
the code wins and the document is a bug to fix.
|
||
|
||
## Current system (verified)
|
||
|
||
- `docs/architecture/current.md` — the system as it actually is: projects, controllers,
|
||
data model, auth, AI pipeline, CI/CD, security posture. **Start here.**
|
||
- `docs/application-discovery-report.md` — full audit and feature inventory.
|
||
- `docs/phase-0-foundation-report.md` — what Phase 0 changed (Job entity, expanded
|
||
pipeline, AI-service lockdown, DateApplied history) and how it was verified.
|
||
- `docs/implementation-roadmap.md` — the phased plan and settled product decisions.
|
||
|
||
## Decisions
|
||
|
||
- `docs/decisions/ADR-002-job-application-model.md` — Job (opportunity) separated from
|
||
JobApplication (pursuit); the reference-not-ownership rule.
|
||
|
||
## Career Workspace — the recovered architecture (governs Phase 2–4)
|
||
|
||
These four documents were recovered from the `feature/career-workspace` branch and are
|
||
the **target architecture** for the Career Workspace. They, plus ADR-002, define how
|
||
career data is stored and how generated documents reference it.
|
||
|
||
- `docs/career-workspace-product-strategy.md` — vision, positioning, personas.
|
||
- `docs/career-workspace-implementation-roadmap.md` — the F0–F5 execution plan.
|
||
- `docs/cv-builder-competitor-deep-research.md` — Novoresume, Reactive Resume, FlowCV,
|
||
Teal, Enhancv, Canva, Resume.io, Kickresume; feature matrix; pricing intelligence.
|
||
- `docs/cv-builder-product-teardown.md` — product teardown.
|
||
- `docs/career-workspace-branch-assessment.md` — per-table recover/migrate/replace verdict
|
||
for the recovered Career/CV tables.
|
||
- `docs/architecture/cv-builder.md` + `docs/architecture/cv-theme-engine.md` — the shipped CV Builder
|
||
(Phase 4/4.5): variant lens over the master profile, data-driven theme engine, public CV routing.
|
||
- `docs/architecture/ai-career-assistant.md` — the shipped AI Workspace (Phase 5): per-application
|
||
suggestion modules, append-only history, provider abstraction, extension points.
|
||
|
||
**Non-negotiable, restated from those documents:** the master career profile is the single
|
||
source of truth. Career data is never duplicated into CVs, applications, or variants — a
|
||
generated document *references* a snapshot; it does not own the data. Job tracking remains
|
||
the primary product; the Career Workspace is a bounded supporting domain.
|
||
|
||
---
|
||
|
||
# Product Identity
|
||
|
||
## Application Name
|
||
|
||
Jobjakt
|
||
|
||
---
|
||
|
||
# What Is Jobjakt?
|
||
|
||
Jobjakt is a job tracking and career management application.
|
||
|
||
The primary purpose is:
|
||
|
||
> Help users organise, manage, and improve their job search.
|
||
|
||
It is not primarily a CV builder.
|
||
|
||
The CV system is a supporting feature.
|
||
|
||
---
|
||
|
||
# Product Hierarchy
|
||
|
||
The product hierarchy is:
|
||
|
||
|
||
CORE PRODUCT
|
||
|
||
Job Tracking
|
||
|
||
↓
|
||
|
||
Applications
|
||
|
||
↓
|
||
|
||
Application Workflow
|
||
|
||
↓
|
||
|
||
Follow-ups
|
||
|
||
↓
|
||
|
||
Communication Tracking
|
||
|
||
SUPPORTING FEATURES
|
||
|
||
Career Profile
|
||
|
||
↓
|
||
|
||
Master CV
|
||
|
||
↓
|
||
|
||
CV Builder
|
||
|
||
↓
|
||
|
||
Cover Letters
|
||
|
||
↓
|
||
|
||
Portfolio
|
||
|
||
↓
|
||
|
||
Interview Preparation
|
||
|
||
ENHANCEMENT FEATURES
|
||
|
||
Job Discovery
|
||
|
||
↓
|
||
|
||
Find Opportunities
|
||
|
||
↓
|
||
|
||
Import Into Tracker
|
||
|
||
|
||
---
|
||
|
||
# Core Principle
|
||
|
||
Do not transform Jobjakt into a CV generator.
|
||
|
||
The competitive advantage is:
|
||
|
||
> Managing the entire journey from discovering a job to successfully applying.
|
||
|
||
---
|
||
|
||
# Target Users
|
||
|
||
Primary user:
|
||
|
||
People actively looking for work.
|
||
|
||
Examples:
|
||
|
||
- Developers.
|
||
- Professionals changing careers.
|
||
- Graduates.
|
||
- Anyone applying for multiple jobs.
|
||
|
||
---
|
||
|
||
# Current Product Goals
|
||
|
||
Priority order:
|
||
|
||
## 1. Excellent Job Tracking
|
||
|
||
Users should easily:
|
||
|
||
- Add jobs.
|
||
- Track status.
|
||
- Manage applications.
|
||
- Follow up.
|
||
- Store communication.
|
||
|
||
---
|
||
|
||
## 2. Excellent Application Workflow
|
||
|
||
A user should be guided through:
|
||
|
||
|
||
Find Job
|
||
|
||
↓
|
||
|
||
Import Job
|
||
|
||
↓
|
||
|
||
Review Details
|
||
|
||
↓
|
||
|
||
Prepare CV
|
||
|
||
↓
|
||
|
||
Prepare Cover Letter
|
||
|
||
↓
|
||
|
||
Add Supporting Files
|
||
|
||
↓
|
||
|
||
Submit Application
|
||
|
||
↓
|
||
|
||
Track Progress
|
||
|
||
|
||
---
|
||
|
||
## 3. Career Workspace
|
||
|
||
Users maintain:
|
||
|
||
One professional identity.
|
||
|
||
This includes:
|
||
|
||
- Personal information.
|
||
- Work history.
|
||
- Education.
|
||
- Skills.
|
||
- Projects.
|
||
- Certifications.
|
||
- Languages.
|
||
- Achievements.
|
||
|
||
This becomes the source of truth.
|
||
|
||
---
|
||
|
||
# Career Architecture
|
||
|
||
The relationship should be:
|
||
|
||
|
||
Career Profile
|
||
|
||
↓
|
||
|
||
Master CV
|
||
|
||
↓
|
||
|
||
CV Builder
|
||
|
||
↓
|
||
|
||
Theme/Layout
|
||
|
||
↓
|
||
|
||
Generated CV
|
||
|
||
|
||
---
|
||
|
||
For applications:
|
||
|
||
|
||
Career Profile
|
||
|
||
↓
|
||
|
||
AI Analysis
|
||
|
||
Job Description
|
||
|
||
↓
|
||
|
||
Tailored CV Draft
|
||
|
||
↓
|
||
|
||
User Review
|
||
|
||
↓
|
||
|
||
Saved Copy Against Application
|
||
|
||
|
||
---
|
||
|
||
Important:
|
||
|
||
The master CV must never be modified automatically.
|
||
|
||
---
|
||
|
||
# CV Builder Vision
|
||
|
||
The CV builder should become similar in quality to:
|
||
|
||
- FlowCV.
|
||
- Novoresume.
|
||
- ElegantCV.
|
||
|
||
Reference research:
|
||
|
||
`docs/research/`
|
||
|
||
---
|
||
|
||
# CV Builder Principles
|
||
|
||
## Content And Design Are Separate
|
||
|
||
Content:
|
||
|
||
- Experience.
|
||
- Skills.
|
||
- Education.
|
||
|
||
Design:
|
||
|
||
- Theme.
|
||
- Colours.
|
||
- Fonts.
|
||
- Layout.
|
||
|
||
---
|
||
|
||
Users should be able to:
|
||
|
||
- Choose themes.
|
||
- Preview instantly.
|
||
- Change colours.
|
||
- Show/hide photo.
|
||
- Configure sections.
|
||
- Export.
|
||
|
||
---
|
||
|
||
# Preferred Builder Experience
|
||
|
||
Structure:
|
||
|
||
|
||
Content Tab
|
||
|
||
↓
|
||
|
||
Customise Tab
|
||
|
||
↓
|
||
|
||
Preview
|
||
|
||
↓
|
||
|
||
Export
|
||
|
||
|
||
---
|
||
|
||
# Themes
|
||
|
||
Initial goal:
|
||
|
||
3-5 excellent themes.
|
||
|
||
Categories:
|
||
|
||
## ATS Professional
|
||
|
||
Simple.
|
||
|
||
Recruiter friendly.
|
||
|
||
|
||
## Modern Professional
|
||
|
||
Clean SaaS style.
|
||
|
||
|
||
## Creative
|
||
|
||
More visual.
|
||
|
||
---
|
||
|
||
Themes should support:
|
||
|
||
- Accent colours.
|
||
- Typography.
|
||
- Layout.
|
||
- Spacing.
|
||
- Photo options.
|
||
- Icons.
|
||
|
||
---
|
||
|
||
# Authentication Requirements
|
||
|
||
Users must support:
|
||
|
||
## Email Signup
|
||
|
||
User can:
|
||
|
||
- Register.
|
||
- Login.
|
||
- Reset password.
|
||
|
||
---
|
||
|
||
## OAuth
|
||
|
||
Support:
|
||
|
||
- Google.
|
||
- Microsoft.
|
||
|
||
If OAuth user does not exist:
|
||
|
||
Create account automatically.
|
||
|
||
---
|
||
|
||
## Security
|
||
|
||
Support:
|
||
|
||
- Password security.
|
||
- Validation.
|
||
- Rate limiting.
|
||
- Two factor authentication.
|
||
|
||
See:
|
||
|
||
`docs/security/`
|
||
|
||
---
|
||
|
||
# AI Philosophy
|
||
|
||
AI assists users.
|
||
|
||
AI does not replace users.
|
||
|
||
---
|
||
|
||
AI can help with:
|
||
|
||
- CV improvements.
|
||
- Job matching.
|
||
- Cover letters.
|
||
- Interview preparation.
|
||
|
||
---
|
||
|
||
AI output must:
|
||
|
||
- Be editable.
|
||
- Require approval.
|
||
- Never invent facts.
|
||
|
||
---
|
||
|
||
See:
|
||
|
||
`docs/ai/`
|
||
|
||
---
|
||
|
||
# Job Search
|
||
|
||
Job search is an enhancement.
|
||
|
||
It should not replace job boards.
|
||
|
||
---
|
||
|
||
Ideal workflow:
|
||
|
||
|
||
Search
|
||
|
||
↓
|
||
|
||
Find Opportunity
|
||
|
||
↓
|
||
|
||
Import Job
|
||
|
||
↓
|
||
|
||
Track Application
|
||
|
||
|
||
---
|
||
|
||
Possible features:
|
||
|
||
- Job title search.
|
||
- Location.
|
||
- Industry.
|
||
- Remote.
|
||
- Filters.
|
||
- Company information.
|
||
|
||
Research required before implementation.
|
||
|
||
---
|
||
|
||
# SaaS Direction
|
||
|
||
Current:
|
||
|
||
Personal application.
|
||
|
||
Future:
|
||
|
||
Commercial SaaS.
|
||
|
||
---
|
||
|
||
Prepare for:
|
||
|
||
- Multiple users.
|
||
- Premium features.
|
||
- AI limits.
|
||
- Storage limits.
|
||
- Premium themes.
|
||
|
||
---
|
||
|
||
Do not over-engineer.
|
||
|
||
Prioritise:
|
||
|
||
Product quality first.
|
||
|
||
---
|
||
|
||
# UI Direction
|
||
|
||
The desired UI style:
|
||
|
||
- Modern.
|
||
- Professional.
|
||
- Notion-inspired.
|
||
- Clean.
|
||
- Easy to navigate.
|
||
- Dark mode support.
|
||
|
||
---
|
||
|
||
Avoid:
|
||
|
||
- Clutter.
|
||
- Complex menus.
|
||
- Confusing workflows.
|
||
|
||
---
|
||
|
||
# UX Principles
|
||
|
||
The application should be:
|
||
|
||
Simple enough for beginners.
|
||
|
||
Powerful enough for serious users.
|
||
|
||
---
|
||
|
||
Users should always understand:
|
||
|
||
Where they are.
|
||
|
||
What they can do.
|
||
|
||
What happens next.
|
||
|
||
---
|
||
|
||
# Development Rules
|
||
|
||
When implementing:
|
||
|
||
## Always
|
||
|
||
- Review existing code first.
|
||
- Make incremental changes.
|
||
- Preserve working functionality.
|
||
- Add tests.
|
||
- Document decisions.
|
||
|
||
---
|
||
|
||
## Avoid
|
||
|
||
- Large rewrites.
|
||
- Breaking migrations.
|
||
- Duplicate systems.
|
||
- Unnecessary dependencies.
|
||
|
||
---
|
||
|
||
# Code Quality
|
||
|
||
Follow:
|
||
|
||
`docs/technical/`
|
||
|
||
---
|
||
|
||
# Architecture
|
||
|
||
Follow:
|
||
|
||
`docs/architecture/`
|
||
|
||
---
|
||
|
||
# Security
|
||
|
||
Follow:
|
||
|
||
`docs/security/`
|
||
|
||
---
|
||
|
||
# AI
|
||
|
||
Follow:
|
||
|
||
`docs/ai/`
|
||
|
||
---
|
||
|
||
# Product Research
|
||
|
||
Follow:
|
||
|
||
`docs/research/`
|
||
|
||
---
|
||
|
||
# Implementation Priority
|
||
|
||
## Phase 1
|
||
|
||
Foundation:
|
||
|
||
- Authentication.
|
||
- User experience.
|
||
- Navigation.
|
||
- Job workflow.
|
||
|
||
---
|
||
|
||
## Phase 2
|
||
|
||
Career Workspace:
|
||
|
||
- Master profile.
|
||
- CV management.
|
||
- Builder.
|
||
|
||
---
|
||
|
||
## Phase 3
|
||
|
||
AI:
|
||
|
||
- Tailoring.
|
||
- Assistance.
|
||
- Recommendations.
|
||
|
||
---
|
||
|
||
## Phase 4
|
||
|
||
Advanced:
|
||
|
||
- Job discovery.
|
||
- Public profiles.
|
||
- SaaS.
|
||
|
||
---
|
||
|
||
# Working Style For AI Assistants
|
||
|
||
When working on Jobjakt:
|
||
|
||
Do not stop after every small task.
|
||
|
||
Work autonomously.
|
||
|
||
Continue improving areas that are safe.
|
||
|
||
---
|
||
|
||
Only request user input when:
|
||
|
||
- A product decision is required.
|
||
- Multiple valid directions exist.
|
||
- Credentials are needed.
|
||
- A destructive decision is required.
|
||
|
||
---
|
||
|
||
If blocked:
|
||
|
||
1. Document the blocker.
|
||
2. Find another useful task.
|
||
3. Continue working.
|
||
|
||
---
|
||
|
||
# Final Goal
|
||
|
||
Jobjakt should become:
|
||
|
||
A premium career workspace.
|
||
|
||
A user should maintain one professional identity and use Jobjakt to:
|
||
|
||
- Find opportunities.
|
||
- Manage applications.
|
||
- Create documents.
|
||
- Improve applications.
|
||
- Track career progress.
|
||
|
||
The CV is one output.
|
||
|
||
The career journey is the product. |