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.