# 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.