docs: reorganize tree, restore architecture + research from archive, add Phase 0 reports

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>
This commit is contained in:
cesnimda
2026-07-17 17:04:32 +02:00
parent aa3567d8a8
commit b176a44627
275 changed files with 12554 additions and 0 deletions
+732
View File
@@ -0,0 +1,732 @@
# 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.
+270
View File
@@ -0,0 +1,270 @@
# Jobjakt Glossary
## Purpose
Defines common terminology used throughout the application.
This prevents ambiguity between product, UX, backend, frontend, and AI development.
---
# Core Terms
## Job
A job opportunity that a user may be interested in.
Examples:
- Software Engineer role.
- Developer position.
- Analyst role.
A Job may exist before an application is submitted.
---
## Job Opportunity
A specific role offered by a company.
Contains:
- Job title.
- Company.
- Description.
- Location.
- Salary information.
- Requirements.
---
## Application
A user's attempt to obtain a specific job.
Relationship:
Company
Job Opportunity
Application
---
## Application Stage
The current state of an application.
Examples:
- Interested
- Preparing
- Applied
- Screening
- Interview
- Offer
- Rejected
- Withdrawn
---
## Company
An organisation offering employment.
Companies are reusable entities.
Example:
A user may apply for:
- Backend Developer
- Frontend Developer
at the same company.
---
# Career Workspace
## Career Profile
The user's professional source of truth.
Contains:
- Personal details.
- Experience.
- Education.
- Skills.
- Projects.
- Certifications.
- Achievements.
The career profile is NOT a CV.
It is the data used to create outputs.
---
## Master CV
A generated representation of the Career Profile.
Purpose:
Provide a default CV.
It can be customised but should originate from the Career Profile.
---
## CV Variant
A different presentation of the same career information.
Examples:
- Software Engineer CV.
- Management CV.
- Academic CV.
Variants should not duplicate career data.
---
## Tailored CV
A CV adapted for a specific job application.
Created from:
Master Career Profile
+
Job Description
+
AI Suggestions
---
## CV Theme
The visual design system used to render a CV.
Contains:
- Layout.
- Typography.
- Colours.
- Spacing.
- Components.
Themes should not contain user data.
---
# AI Terms
## AI Provider
A service capable of generating AI responses.
Examples:
- OpenAI.
- Gemini.
- Claude.
- Ollama.
---
## AI Generation
Any content created or improved by AI.
Examples:
- CV bullet improvements.
- Cover letters.
- Job matching.
---
## AI Suggestion
A recommendation from AI that requires user approval.
---
# Documents
## Cover Letter
A document explaining why a user is suitable for a specific role.
---
## Portfolio
A collection of professional work.
Examples:
- Projects.
- Case studies.
- Publications.
---
# User
A person using Jobjakt.
---
# Admin
A user with system management permissions.
Admins manage:
- AI providers.
- System settings.
- Feature controls.
---
# Career Workspace
The collection of tools supporting the user's career development.
Includes:
- Career Profile.
- CV Builder.
- Cover Letters.
- Portfolio.
- Future career tools.
---
# SaaS
Future commercial version of Jobjakt.
Potential features:
- Subscriptions.
- Premium themes.
- AI limits.
- Storage limits.
+105
View File
@@ -0,0 +1,105 @@
# Product Principles
## Purpose
Defines the principles that guide product decisions.
---
# Principle 1
## Job Tracking Comes First
Jobjakt exists primarily to help users manage their job search.
Every major decision should support:
- Finding jobs.
- Applying efficiently.
- Tracking progress.
- Improving outcomes.
---
# Principle 2
## Career Data Is the Foundation
Users should maintain one professional identity.
The application should avoid:
- Multiple disconnected profiles.
- Re-entering information.
- Duplicating career history.
---
# Principle 3
## AI Assists, Humans Decide
AI should:
- Suggest.
- Improve.
- Analyse.
- Accelerate.
AI should not:
- Replace user judgement.
- Modify facts silently.
- Invent experience.
---
# Principle 4
## Simplicity Over Complexity
Powerful features should remain approachable.
Avoid:
- Complex workflows.
- Excessive configuration.
- Feature overload.
---
# Principle 5
## Progressive Disclosure
Show users what they need when they need it.
Example:
New users:
Simple CV creation.
Advanced users:
Custom themes, AI tools, detailed controls.
---
# Principle 6
## Quality Over Quantity
A small number of excellent features is better than many unfinished features.
---
# Principle 7
## SaaS Ready, Not SaaS First
Architecture should allow future growth.
However:
Do not sacrifice user experience today for hypothetical future requirements.
+113
View File
@@ -0,0 +1,113 @@
# Design Principles
## Goal
Create a premium, modern career management experience.
---
# Visual Direction
The application should feel:
- Professional.
- Modern.
- Calm.
- Intelligent.
- Trustworthy.
---
# Inspirations
## Notion
For:
- Organisation.
- Clean interfaces.
- Flexible content.
## Linear
For:
- Professional software feel.
- Speed.
- Keyboard-friendly workflows.
## FlowCV
For:
- CV creation experience.
- Template selection.
- Visual editing.
## Jobscan
For:
- Career optimisation.
---
# Navigation
Users should always understand:
Where am I?
What can I do?
What happens next?
---
# Forms
Forms should:
- Be grouped logically.
- Explain fields.
- Validate clearly.
- Avoid unnecessary questions.
---
# Empty States
Every empty state should explain:
- Why it matters.
- What action to take.
- How to get started.
---
# Errors
Errors should:
- Explain what happened.
- Suggest next steps.
- Avoid technical language.
---
# Dark Mode
Dark mode should be supported.
It should feel designed, not inverted.
---
# Accessibility
All features should consider:
- Keyboard navigation.
- Screen readers.
- Contrast.
- Clear focus states.
+90
View File
@@ -0,0 +1,90 @@
# AI Session Start Instructions
Before making changes:
1. Read:
docs/MASTER_IMPLEMENTATION_GUIDE.md
2. Read relevant documentation:
docs/product/
docs/architecture/
docs/security/
docs/technical/
3. Review:
- Current git status.
- Recent changes.
- Existing implementation.
---
# Working Rules
You are working on an existing production application.
Do not:
- Rewrite without justification.
- Remove working features.
- Change architecture without understanding impact.
- Assume documentation is correct over code.
---
# Before Coding
Explain:
- What you found.
- What needs changing.
- Why.
For larger changes:
Create an implementation plan.
---
# During Coding
Prefer:
- Small commits.
- Clean abstractions.
- Tests.
- Documentation updates.
---
# Continue Working
Do not stop after every small task.
Continue with related improvements.
Only ask for input when:
- A decision cannot reasonably be inferred.
- Multiple options have significant consequences.
- Credentials/access are required.
- A destructive choice is required.
---
# After Work
Update:
docs/CHANGELOG_AI_WORK.md
Include:
- Summary.
- Files changed.
- Tests.
- Decisions.
- Next steps.
+212
View File
@@ -0,0 +1,212 @@
# AI Development Changelog
This document tracks work completed by AI coding assistants.
Purpose:
- Maintain project history.
- Record architectural decisions.
- Track incomplete work.
- Prevent repeated investigations.
- Help future AI sessions understand previous changes.
---
# How To Use
After making meaningful changes, update this file.
Include:
- Date.
- Task.
- Summary.
- Files changed.
- Decisions.
- Testing performed.
- Remaining work.
---
# Current Status
## Application State
Status:
Active development.
The application is functional but undergoing major UX, architecture, and product improvements.
---
# Completed Work
## Authentication
Status:
In progress.
Completed:
- Existing authentication reviewed.
- OAuth architecture analysed.
Remaining:
- Full signup flow.
- Google login.
- Microsoft login.
- Password reset improvements.
- Two factor authentication.
---
## Career Workspace
Status:
Planning phase.
Completed:
- Product direction defined.
- Architecture documented.
- Competitor research completed.
Remaining:
- Master career profile.
- CV builder redesign.
- Theme system.
- AI workflows.
---
## Job Workflow
Status:
Core product.
Completed:
- Existing job tracking functionality.
Remaining:
- Improved add-job workflow.
- Better application pipeline.
- Better onboarding.
---
# Current Development Session
Date:
YYYY-MM-DD
## Objective
Describe current goal.
---
## Work Completed
Example:
- Updated authentication pages.
- Refactored settings layout.
- Added validation.
---
## Files Changed
Example:
Backend:
- path/file.cs
Frontend:
- path/file.tsx
Documentation:
- docs/file.md
---
## Testing
Completed:
- Build successful.
- Tests passed.
Not completed:
- Manual testing required.
- External service testing required.
---
# Architectural Decisions
## Decision
Date:
Reason:
Impact:
---
# Known Issues
## Issue
Description:
Possible causes:
Next investigation:
---
# Blocked Items
## Item
Reason blocked:
Required input:
---
# Recommended Next Tasks
Priority order:
1.
2.
3.
---
# AI Notes
Important context for future sessions:
- Read MASTER_IMPLEMENTATION_GUIDE.md first.
- Do not redesign without reviewing existing architecture.
- Prefer incremental changes.
- Ask before destructive decisions.
+707
View File
@@ -0,0 +1,707 @@
# Jobjakt Master Implementation Guide
Version: 1.0
---
# Purpose Of This Document
This document is the primary source of truth for understanding and improving Jobjakt.
Before making significant changes:
1. Read this document.
2. Read the relevant linked documentation.
3. Understand existing architecture.
4. Make incremental improvements.
Do not redesign based on assumptions.
Always verify against the actual codebase.
---
# 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:
1. Document the blocker.
2. Find another useful task.
3. 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.
View File
View File
View File
View File
+20
View File
@@ -0,0 +1,20 @@
# Jobjakt Development Context
Before making changes:
1. Read docs/00-ai-context.md
2. Read relevant feature documentation
3. Check existing implementation
4. Prefer incremental changes
The application is a job tracking platform.
The CV builder is a supporting Career Workspace feature.
Never redesign Jobjakt into only a CV builder.
Existing working functionality must be preserved.
When uncertain:
- Ask for clarification.
- Do not make large assumptions.
+732
View File
@@ -0,0 +1,732 @@
# 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.
+270
View File
@@ -0,0 +1,270 @@
# Jobjakt Glossary
## Purpose
Defines common terminology used throughout the application.
This prevents ambiguity between product, UX, backend, frontend, and AI development.
---
# Core Terms
## Job
A job opportunity that a user may be interested in.
Examples:
- Software Engineer role.
- Developer position.
- Analyst role.
A Job may exist before an application is submitted.
---
## Job Opportunity
A specific role offered by a company.
Contains:
- Job title.
- Company.
- Description.
- Location.
- Salary information.
- Requirements.
---
## Application
A user's attempt to obtain a specific job.
Relationship:
Company
Job Opportunity
Application
---
## Application Stage
The current state of an application.
Examples:
- Interested
- Preparing
- Applied
- Screening
- Interview
- Offer
- Rejected
- Withdrawn
---
## Company
An organisation offering employment.
Companies are reusable entities.
Example:
A user may apply for:
- Backend Developer
- Frontend Developer
at the same company.
---
# Career Workspace
## Career Profile
The user's professional source of truth.
Contains:
- Personal details.
- Experience.
- Education.
- Skills.
- Projects.
- Certifications.
- Achievements.
The career profile is NOT a CV.
It is the data used to create outputs.
---
## Master CV
A generated representation of the Career Profile.
Purpose:
Provide a default CV.
It can be customised but should originate from the Career Profile.
---
## CV Variant
A different presentation of the same career information.
Examples:
- Software Engineer CV.
- Management CV.
- Academic CV.
Variants should not duplicate career data.
---
## Tailored CV
A CV adapted for a specific job application.
Created from:
Master Career Profile
+
Job Description
+
AI Suggestions
---
## CV Theme
The visual design system used to render a CV.
Contains:
- Layout.
- Typography.
- Colours.
- Spacing.
- Components.
Themes should not contain user data.
---
# AI Terms
## AI Provider
A service capable of generating AI responses.
Examples:
- OpenAI.
- Gemini.
- Claude.
- Ollama.
---
## AI Generation
Any content created or improved by AI.
Examples:
- CV bullet improvements.
- Cover letters.
- Job matching.
---
## AI Suggestion
A recommendation from AI that requires user approval.
---
# Documents
## Cover Letter
A document explaining why a user is suitable for a specific role.
---
## Portfolio
A collection of professional work.
Examples:
- Projects.
- Case studies.
- Publications.
---
# User
A person using Jobjakt.
---
# Admin
A user with system management permissions.
Admins manage:
- AI providers.
- System settings.
- Feature controls.
---
# Career Workspace
The collection of tools supporting the user's career development.
Includes:
- Career Profile.
- CV Builder.
- Cover Letters.
- Portfolio.
- Future career tools.
---
# SaaS
Future commercial version of Jobjakt.
Potential features:
- Subscriptions.
- Premium themes.
- AI limits.
- Storage limits.
+105
View File
@@ -0,0 +1,105 @@
# Product Principles
## Purpose
Defines the principles that guide product decisions.
---
# Principle 1
## Job Tracking Comes First
Jobjakt exists primarily to help users manage their job search.
Every major decision should support:
- Finding jobs.
- Applying efficiently.
- Tracking progress.
- Improving outcomes.
---
# Principle 2
## Career Data Is the Foundation
Users should maintain one professional identity.
The application should avoid:
- Multiple disconnected profiles.
- Re-entering information.
- Duplicating career history.
---
# Principle 3
## AI Assists, Humans Decide
AI should:
- Suggest.
- Improve.
- Analyse.
- Accelerate.
AI should not:
- Replace user judgement.
- Modify facts silently.
- Invent experience.
---
# Principle 4
## Simplicity Over Complexity
Powerful features should remain approachable.
Avoid:
- Complex workflows.
- Excessive configuration.
- Feature overload.
---
# Principle 5
## Progressive Disclosure
Show users what they need when they need it.
Example:
New users:
Simple CV creation.
Advanced users:
Custom themes, AI tools, detailed controls.
---
# Principle 6
## Quality Over Quantity
A small number of excellent features is better than many unfinished features.
---
# Principle 7
## SaaS Ready, Not SaaS First
Architecture should allow future growth.
However:
Do not sacrifice user experience today for hypothetical future requirements.
+113
View File
@@ -0,0 +1,113 @@
# Design Principles
## Goal
Create a premium, modern career management experience.
---
# Visual Direction
The application should feel:
- Professional.
- Modern.
- Calm.
- Intelligent.
- Trustworthy.
---
# Inspirations
## Notion
For:
- Organisation.
- Clean interfaces.
- Flexible content.
## Linear
For:
- Professional software feel.
- Speed.
- Keyboard-friendly workflows.
## FlowCV
For:
- CV creation experience.
- Template selection.
- Visual editing.
## Jobscan
For:
- Career optimisation.
---
# Navigation
Users should always understand:
Where am I?
What can I do?
What happens next?
---
# Forms
Forms should:
- Be grouped logically.
- Explain fields.
- Validate clearly.
- Avoid unnecessary questions.
---
# Empty States
Every empty state should explain:
- Why it matters.
- What action to take.
- How to get started.
---
# Errors
Errors should:
- Explain what happened.
- Suggest next steps.
- Avoid technical language.
---
# Dark Mode
Dark mode should be supported.
It should feel designed, not inverted.
---
# Accessibility
All features should consider:
- Keyboard navigation.
- Screen readers.
- Contrast.
- Clear focus states.
+3
View File
@@ -0,0 +1,3 @@
# overview
TODO: Complete documentation.
+3
View File
@@ -0,0 +1,3 @@
# prompts
TODO: Complete documentation.
+3
View File
@@ -0,0 +1,3 @@
# providers
TODO: Complete documentation.
+3
View File
@@ -0,0 +1,3 @@
# safety
TODO: Complete documentation.
@@ -0,0 +1,3 @@
# backend
TODO: Complete documentation.
@@ -0,0 +1,3 @@
# current
TODO: Complete documentation.
@@ -0,0 +1,3 @@
# database
TODO: Complete documentation.
@@ -0,0 +1,3 @@
# deployment
TODO: Complete documentation.
@@ -0,0 +1,3 @@
# frontend
TODO: Complete documentation.
@@ -0,0 +1,3 @@
# future
TODO: Complete documentation.
+3
View File
@@ -0,0 +1,3 @@
# 2fa
TODO: Complete documentation.
+3
View File
@@ -0,0 +1,3 @@
# login
TODO: Complete documentation.
+3
View File
@@ -0,0 +1,3 @@
# oauth
TODO: Complete documentation.
+3
View File
@@ -0,0 +1,3 @@
# overview
TODO: Complete documentation.
+3
View File
@@ -0,0 +1,3 @@
# signup
TODO: Complete documentation.
+3
View File
@@ -0,0 +1,3 @@
# education
TODO: Complete documentation.
+3
View File
@@ -0,0 +1,3 @@
# experience
TODO: Complete documentation.
@@ -0,0 +1,3 @@
# master-profile
TODO: Complete documentation.
+3
View File
@@ -0,0 +1,3 @@
# overview
TODO: Complete documentation.
+3
View File
@@ -0,0 +1,3 @@
# projects
TODO: Complete documentation.
+3
View File
@@ -0,0 +1,3 @@
# skills
TODO: Complete documentation.
+3
View File
@@ -0,0 +1,3 @@
# ai
TODO: Complete documentation.
@@ -0,0 +1,3 @@
# builder
TODO: Complete documentation.
@@ -0,0 +1,3 @@
# overview
TODO: Complete documentation.
+3
View File
@@ -0,0 +1,3 @@
# ai
TODO: Complete documentation.
+3
View File
@@ -0,0 +1,3 @@
# content
TODO: Complete documentation.
@@ -0,0 +1,3 @@
# customisation
TODO: Complete documentation.
+3
View File
@@ -0,0 +1,3 @@
# exports
TODO: Complete documentation.
@@ -0,0 +1,3 @@
# overview
TODO: Complete documentation.
@@ -0,0 +1,3 @@
# rendering
TODO: Complete documentation.
+3
View File
@@ -0,0 +1,3 @@
# themes
TODO: Complete documentation.
@@ -0,0 +1,3 @@
# workflow
TODO: Complete documentation.
@@ -0,0 +1,3 @@
# documentation-rules
TODO: Complete documentation.
+3
View File
@@ -0,0 +1,3 @@
# applications
TODO: Complete documentation.
+3
View File
@@ -0,0 +1,3 @@
# companies
TODO: Complete documentation.
+3
View File
@@ -0,0 +1,3 @@
# followups
TODO: Complete documentation.
+3
View File
@@ -0,0 +1,3 @@
# job-import
TODO: Complete documentation.
+3
View File
@@ -0,0 +1,3 @@
# job-search
TODO: Complete documentation.
+3
View File
@@ -0,0 +1,3 @@
# overview
TODO: Complete documentation.
@@ -0,0 +1,3 @@
# business-model
TODO: Complete documentation.

Some files were not shown because too many files have changed in this diff Show More