# AI Development Context
## Jobjakt

Version: 1.0
Status: Living document
Last Updated: YYYY-MM-DD

---

# Purpose

This document is the primary source of truth for AI-assisted development.

Every AI assistant (Claude Code, Codex, ChatGPT, GitHub Copilot, etc.) should read this document before making architectural decisions or implementing new features.

If another document conflicts with this file, this file takes precedence unless an Architecture Decision Record (ADR) explicitly supersedes it.

---

# What is Jobjakt?

Jobjakt is an AI-powered job tracking and career management platform.

Its purpose is to help people organise, improve and manage their entire job search from one place.

Unlike traditional job trackers, Jobjakt assists users throughout the complete application lifecycle using AI-powered career tools.

The application is designed to evolve into a SaaS platform but currently prioritises an excellent single-user experience.

---

# Product Philosophy

Jobjakt is NOT:

- just a CV builder
- just another AI wrapper
- another job board
- another Kanban clone

Instead, Jobjakt is a Career Workspace.

The job tracking workflow remains the primary product.

Everything else exists to improve the user's ability to secure employment.

Always remember:

Jobs are the product.

Career tools support the product.

Never invert this relationship.

---

# Product Hierarchy

Core Product

Job Tracking

↓

Applications

↓

Application Workflow

↓

Communication

↓

Follow Ups

↓

Career Workspace

↓

Career Profile

↓

CV Builder

↓

Cover Letters

↓

Portfolio

↓

Interview Preparation

↓

Future Career Outputs

Future enhancements should strengthen this workflow, never replace it.

---

# Target Audience

Primary:

- Individual job seekers

Secondary:

- Graduates
- Career changers
- Software engineers
- Technical professionals
- Knowledge workers

Future:

- SaaS customers
- Premium subscribers

There is currently no requirement for recruiter functionality.

---

# Design Philosophy

The application should feel:

- Modern
- Professional
- Fast
- Calm
- Clean
- Premium
- AI-native
- Notion-inspired
- Productivity focused

Primary inspirations:

- Notion
- Linear
- FlowCV
- Jobscan

Avoid:

- clutter
- unnecessary dialogs
- confusing navigation
- feature overload
- excessive configuration

The UI should feel approachable while remaining powerful.

---

# Core Principles

## Principle 1

Working software is more valuable than rewrites.

Prefer incremental improvements.

---

## Principle 2

Do not rewrite large areas unless absolutely necessary.

Refactor gradually.

---

## Principle 3

Preserve backwards compatibility wherever practical.

---

## Principle 4

Every new feature should integrate naturally into the existing workflow.

Avoid bolting features onto random pages.

---

## Principle 5

Reduce complexity whenever possible.

If something can be achieved with one screen instead of three, prefer one.

---

## Principle 6

Everything should have one obvious place.

Avoid duplicated functionality.

---

# Core Workflow

The application revolves around a single journey.

Discover Job

↓

Import Job

↓

Review Job

↓

Apply

↓

Track Progress

↓

Receive Communication

↓

Prepare Interview

↓

Accept / Reject Offer

Career tools enhance this process.

---

# Career Workspace

Career Workspace is the second major feature area.

It should never overshadow Job Tracking.

Purpose:

Maintain one structured professional profile.

Generate multiple outputs.

Everything should originate from one source of truth.

---

# Source of Truth

There is exactly ONE master career profile.

It contains:

- personal information
- experience
- education
- skills
- projects
- certifications
- languages
- awards
- publications
- organisations
- references

Users may edit this manually at any time.

The master profile is never automatically overwritten.

---

# CV Strategy

The CV builder is NOT the user's data.

It is only a presentation layer.

Relationship:

Master Career Profile

↓

CV Builder

↓

Theme

↓

Generated CV

↓

PDF / HTML / DOCX

Never duplicate user data between templates.

---

# Tailored CV Strategy

Users create tailored CVs from their master profile.

Workflow:

Master Career Profile

↓

Job Analysis

↓

AI Suggestions

↓

User Review

↓

User Edits

↓

Save Against Application

↓

Export

Users may manually edit every generated CV.

AI never has final control.

---

# Public CVs

Supported feature.

Users can choose whether a CV is public.

If enabled:

Generate:

/cv/{random-guid}

No usernames initially.

Privacy first.

---

# Job Tracking

The application revolves around Applications.

Data hierarchy:

Company

↓

Job Opportunity

↓

Application

↓

Communication

↓

Follow Ups

↓

Documents

Companies are reusable.

Users may apply for multiple roles at the same company.

---

# Communication

Every application should eventually contain:

- Emails
- Notes
- Follow Ups
- Attachments
- Timeline
- AI Insights

---

# User Journey

Ideal onboarding:

Register

↓

Verify Email

↓

Create Profile

↓

Import CV

↓

Review Career Profile

↓

Connect Email

↓

Import First Job

↓

Generate First CV

↓

Begin Tracking Applications

The onboarding experience should guide the user through this journey.

---

# Authentication

Supported:

- Email/password
- Google
- Microsoft

Future:

- Passkeys
- Additional OAuth providers

Security features:

- Email verification
- Password reset
- 2FA
- CAPTCHA
- Rate limiting
- Session management

---

# AI

The application supports multiple providers.

Architecture:

Provider Interface

↓

OpenAI

Gemini

Claude

Ollama

Future Providers

The admin controls available providers.

Users should never be locked into one AI model.

---

# AI Behaviour

AI assists.

Users decide.

AI must never silently alter important user data.

Every generated result should be reviewable.

---

# UI Principles

Every page should:

Have one clear purpose.

One primary action.

Consistent spacing.

Consistent typography.

Predictable navigation.

Avoid overwhelming new users.

---

# CV Builder Inspiration

Reference applications:

FlowCV

ElegantCV

Reactive Resume

Novoresume

Purpose:

Study:

- UX
- Workflows
- Features
- Theme systems

Do NOT:

- Copy code
- Copy branding
- Copy assets

---

# HTML Reference

Reference HTML:

D:\FlowCV

For research only.

Never copy.

---

# Future Vision

The application should gradually evolve into a Career Workspace.

Possible future outputs:

- CV
- Cover Letter
- Public Profile
- Portfolio
- LinkedIn Summary
- Interview Preparation
- Personal Website

These all originate from one career profile.

---

# SaaS Readiness

Architecture should support:

- subscriptions
- premium themes
- AI limits
- storage limits
- billing
- Stripe
- feature flags

Do not over-engineer before needed.

Excellent UX is more important.

---

# Coding Philosophy

Prefer:

Small services

Small components

Good naming

Composition

Dependency injection

Testability

Readable code

Avoid:

Massive controllers

God services

Duplicated logic

Large React components

Magic strings

Hidden business logic

---

# Working Style

Before implementing anything:

1. Read relevant documentation.
2. Analyse current implementation.
3. Compare current state with target state.
4. Produce a short implementation plan.
5. Implement incrementally.
6. Update documentation.
7. Test thoroughly.

---

# Decision Making

When multiple solutions exist:

Choose the solution that:

- improves UX
- reduces maintenance
- keeps architecture clean
- supports future SaaS
- preserves current functionality

---

# What AI Should Never Do

Never:

Rewrite the application from scratch.

Break existing functionality.

Duplicate existing systems.

Ignore existing architecture.

Remove features without justification.

Invent requirements.

Ignore documentation.

---

# Documentation

Whenever a significant architectural decision is made:

Create or update an ADR.

Keep documentation current.

Documentation is considered part of the application.

---

# Final Reminder

Jobjakt exists to help people get jobs.

Every feature should ultimately help users:

- discover opportunities
- apply faster
- improve applications
- stay organised
- secure interviews
- secure employment

If a proposed feature does not support that mission, reconsider whether it belongs in the product.