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>
9.2 KiB
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:
- Read this document (direction and non-negotiables).
- Read the relevant linked documentation (below).
- Understand existing architecture — verify against the actual codebase.
- 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:
- Document the blocker.
- Find another useful task.
- 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.