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>
2026-07-17 17:04:32 +02:00
parent aa3567d8a8
commit b176a44627
275 changed files with 12554 additions and 0 deletions
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -0,0 +1,3 @@
+# overview
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# prompts
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# providers
+
+TODO: Complete documentation.
@@ -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.
@@ -0,0 +1,3 @@
+# 2fa
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# login
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# oauth
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# overview
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# signup
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# education
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# experience
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# master-profile
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# overview
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# projects
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# skills
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# ai
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# builder
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# overview
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# ai
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# content
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# customisation
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# exports
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# overview
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# rendering
+
+TODO: Complete documentation.
@@ -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.
@@ -0,0 +1,3 @@
+# applications
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# companies
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# followups
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# job-import
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# job-search
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# overview
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# business-model
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# goals
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# mission
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# non-goals
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# personas
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# roadmap
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# vision
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# flowcv
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# jobscan
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# novoresume
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# reactive-resume
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# overview
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# privacy
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# uploads
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# validation
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# accessibility
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# dashboard
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# design-system
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# navigation
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# onboarding
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# profile
+
+TODO: Complete documentation.
@@ -0,0 +1,3 @@
+# settings
+
+TODO: Complete documentation.