cesnimda
b176a44627
Active docs/ was stub scaffolding while the real docs sat in docs/_archive/. Restore and correct them, and record the Phase 0 work. - docs/architecture/current.md: verified system map (from archived SYSTEM_OVERVIEW, 9 corrections against code). - docs/research/competitors.md: sourced competitor analysis (from archived PRODUCT_RESEARCH, feature matrix corrected). - docs/decisions/ADR-002-job-application-model.md: the Job/JobApplication split. - docs/application-discovery-report.md, docs/implementation-roadmap.md, docs/phase-0-foundation-report.md, docs/career-workspace-branch-assessment.md. - Remove 10 zero-byte placeholder files that advertised content that never existed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
8.3 KiB
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
- 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:
- Read relevant documentation.
- Analyse current implementation.
- Compare current state with target state.
- Produce a short implementation plan.
- Implement incrementally.
- Update documentation.
- 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.