cesnimda
719 lines
8.7 KiB
Markdown
719 lines
8.7 KiB
Markdown
# AI Development Context
|
|
## Jobjakt
|
|
|
|
Version: 1.0
|
|
Status: Living document
|
|
Last Updated: 2026-07-30
|
|
|
|
---
|
|
|
|
# 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 deployment selects one AI provider with the `AI_PROVIDER` environment variable. The supported
|
|
providers are Ollama, Gemini, and Groq; OpenAI and Claude are not implemented. The .NET API calls the
|
|
private `ai-service` through `ISummarizerService`, and the provider is never selected by an end user or
|
|
an administrator at request time.
|
|
|
|
Ollama is the privacy-first local option. Cloud providers are deployment choices for operators who
|
|
accept their data-handling and cost trade-offs. Keep this boundary until customer demand justifies a
|
|
more complex provider router. See `docs/decisions/ADR-004-ai-provider-system.md`.
|
|
|
|
---
|
|
|
|
# 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. |