docs: consolidate repository guides and preserve audit history

2026-09-11 14:22:41 +02:00
parent 115441a409
commit 682a3028bb
404 changed files with 3402 additions and 2621 deletions
@@ -0,0 +1,52 @@
+# Coding Standards
+
+## General Rules
+
+Code should be:
+
+- Readable.
+- Self documenting.
+- Consistent.
+
+---
+
+# Naming
+
+Use meaningful names.
+
+Avoid:
+
+- Short unclear variables.
+- Generic service names.
+
+---
+
+# Methods
+
+Prefer:
+
+Small focused methods.
+
+Avoid:
+
+Large methods handling multiple responsibilities.
+
+---
+
+# Error Handling
+
+Errors should:
+
+- Be handled explicitly.
+- Provide useful messages.
+- Not expose sensitive information.
+
+---
+
+# Comments
+
+Comments should explain:
+
+Why something exists.
+
+Not what the code does.
@@ -0,0 +1,41 @@
+# Deployment
+
+## Current Goal
+
+Reliable production deployments.
+
+---
+
+# Deployment Requirements
+
+Before deploying:
+
+- Build succeeds.
+- Tests pass.
+- Database migrations reviewed.
+
+---
+
+# Production Safety
+
+Avoid:
+
+- Breaking migrations.
+- Downtime.
+- Lost data.
+
+---
+
+# Rollback
+
+Every deployment should have a recovery plan.
+
+---
+
+# Future SaaS
+
+Consider:
+
+- Automated deployments.
+- Staging environment.
+- Deployment approvals.
@@ -0,0 +1,51 @@
+# Docker
+
+## Purpose
+
+Maintain consistent environments.
+
+---
+
+# Requirements
+
+Containers should:
+
+- Have clear names.
+- Use health checks.
+- Log correctly.
+
+---
+
+# Images
+
+Prefer:
+
+- Official images.
+- Pinned versions.
+
+---
+
+# Volumes
+
+Important data must use persistent storage.
+
+---
+
+# Production
+
+Monitor:
+
+- Container health.
+- Memory usage.
+- Disk usage.
+- Restarts.
+
+---
+
+# Common Issues
+
+Investigate:
+
+- Container crashes.
+- Storage exhaustion.
+- Network issues.
@@ -0,0 +1,32 @@
+# Environment Configuration
+
+## Principles
+
+Never hardcode secrets.
+
+---
+
+# Configuration
+
+Use:
+
+- Environment variables.
+- Secret storage.
+
+---
+
+# Examples
+
+Database credentials.
+
+API keys.
+
+OAuth secrets.
+
+AI provider keys.
+
+---
+
+# Development
+
+Local configuration should not affect production.
@@ -0,0 +1,53 @@
+# Git Workflow
+
+## Branches
+
+Use feature branches.
+
+Examples:
+
+feature/cv-builder-themes
+
+feature/google-auth
+
+fix/pdf-parser
+
+---
+
+# Commits
+
+Commits should:
+
+- Describe the change.
+- Be focused.
+- Be reviewable.
+
+---
+
+# Commit Style
+
+Examples:
+
+feat: add CV theme selector
+
+fix: correct PDF extraction
+
+refactor: extract AI service
+
+docs: update architecture
+
+---
+
+# Before Commit
+
+Check:
+
+- Tests pass.
+- Build succeeds.
+- No secrets included.
+
+---
+
+# Deployment
+
+Do not deploy untested breaking changes.
@@ -0,0 +1,55 @@
+# Logging
+
+## Purpose
+
+Make debugging possible.
+
+---
+
+# Log Levels
+
+Use:
+
+Trace.
+
+Debug.
+
+Information.
+
+Warning.
+
+Error.
+
+Critical.
+
+---
+
+# Do Not Log
+
+Never log:
+
+- Passwords.
+- Tokens.
+- API keys.
+- Private documents.
+
+---
+
+# Useful Logs
+
+Include:
+
+- Operation.
+- User context where safe.
+- Error details.
+- Correlation IDs.
+
+## Runtime output
+
+Production emits structured JSON to stdout for Docker collection. Development keeps readable console
+and debug output. The request middleware records method, path, status, elapsed milliseconds, trace ID,
+and authenticated subject when present. Unhandled errors use the same trace ID in their Problem Details
+response so an operator can correlate the client report with `docker logs`.
+
+Compose retains three 10 MB local log files per service. There is no external sink; add Seq/OTLP only
+when single-node Docker logs stop being operationally sufficient.
@@ -0,0 +1,39 @@
+# Monitoring
+
+## Purpose
+
+Detect problems early.
+
+---
+
+# Monitor
+
+Application:
+
+- Errors.
+- Response times.
+- Background jobs.
+
+Infrastructure:
+
+- CPU.
+- Memory.
+- Disk.
+- Containers.
+
+---
+
+# Alerts
+
+Important alerts:
+
+- Application unavailable.
+- Database errors.
+- Failed deployments.
+- Storage issues.
+
+---
+
+# User Experience
+
+Errors should be visible internally before users report them.
@@ -0,0 +1,41 @@
+# Technical Overview
+
+## Purpose
+
+Define engineering standards for Jobjakt development.
+
+These guidelines help maintain:
+
+- Code quality.
+- Reliability.
+- Security.
+- Maintainability.
+
+---
+
+# Development Philosophy
+
+Prefer:
+
+- Simple solutions.
+- Clear code.
+- Incremental improvements.
+- Tested changes.
+
+Avoid:
+
+- Premature optimisation.
+- Large rewrites.
+- Unnecessary dependencies.
+
+---
+
+# Engineering Priorities
+
+Order of importance:
+
+1. User experience.
+2. Reliability.
+3. Security.
+4. Maintainability.
+5. Performance.
@@ -0,0 +1,36 @@
+# Performance
+
+## Principles
+
+Optimise based on evidence.
+
+---
+
+# Important Areas
+
+Database:
+
+- Query efficiency.
+- Indexes.
+
+Frontend:
+
+- Bundle size.
+- Rendering.
+
+Backend:
+
+- Expensive operations.
+
+AI:
+
+- Token usage.
+- Response time.
+
+---
+
+# Avoid
+
+Optimising prematurely.
+
+Complex caching without measurements.
@@ -0,0 +1,65 @@
+# Testing Strategy
+
+## Goal
+
+Maintain confidence while changing the application.
+
+---
+
+# Test Areas
+
+## Backend
+
+Test:
+
+- Business logic.
+- Services.
+- APIs.
+- Database behaviour.
+
+---
+
+## Frontend
+
+Test:
+
+- Important workflows.
+- Components.
+- User interactions.
+
+---
+
+# Priority Workflows
+
+Must protect:
+
+## Authentication
+
+- Signup.
+- Login.
+- OAuth.
+- Password reset.
+- 2FA.
+
+---
+
+## Jobs
+
+- Creating jobs.
+- Updating status.
+- Follow-ups.
+
+---
+
+## Career
+
+- CV upload.
+- CV extraction.
+- CV generation.
+- PDF generation.
+
+---
+
+# Production Confidence
+
+Critical user journeys should have automated tests.
@@ -0,0 +1,32 @@
+# Troubleshooting
+
+## Purpose
+
+Provide debugging approach.
+
+---
+
+# General Process
+
+1. Reproduce issue.
+2. Check logs.
+3. Identify affected component.
+4. Make smallest safe fix.
+5. Verify.
+
+---
+
+# Production Issues
+
+Check:
+
+- Application logs.
+- Docker status.
+- Database.
+- External services.
+
+---
+
+# Never
+
+Do not randomly change production configuration without understanding the cause.