docs: add deployment and technical documentation

[OlaszPL]

Overview

Add comprehensive deployment and technical documentation so the project can be set up, understood, and run end-to-end without reading the source.

Context

The project lacked a single, self-contained reference for how to deploy the system and how it works internally. This adds both, and aligns the existing READMEs with the documented requirements.

Changes

• Add docs/DEPLOYMENT.md: step-by-step setup for both Docker and bare-metal/VM, including the full environment variable reference.
• Add docs/TECHNICAL-DOCUMENTATION.md: architecture, technology stack, security and authentication model, and the persistence/concurrency model.
• Link both guides from the root README.md and add a Documentation section.
• Align the Node.js requirement to 22 in the root and frontend READMEs.
• Document the ENVIRONMENT/ENV variable in backend/.env.example, noting it defaults to development and that production fails fast when ADMIN_PASSWORD_HASH or JWT_SECRET is missing.

Risks & Impact

Documentation-only change; no runtime code paths are affected.

Rollback Plan

Revert the single commit; no data or migration considerations.

Related

Relates RDE-89

Checklist

• Title is concise and imperative
• Scope is focused
• Docs updated (this PR is the docs)

Summary by CodeRabbit

• Documentation
  • Updated main README to include a structured Documentation section (with links) and clarified prerequisites
  • Added a comprehensive production deployment guide covering Docker and non-Docker workflows, environment variables, required production secrets, and verification/troubleshooting
  • Added full technical documentation covering architecture, security/authentication, persistence, endpoint behavior, and environment variable reference
  • Updated frontend prerequisites to require Node.js 22 (and adjusted install instructions)

[linear-code]

RDE-89

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: a0df9771-87e3-448b-90a6-5d24d3b3e031

📥 Commits

Reviewing files that changed from the base of the PR and between 540603d and 2e0366e.

📒 Files selected for processing (4)

• docs/DEPLOYMENT.md
• docs/TECHNICAL-DOCUMENTATION.md
• docs/storage-and-lifecycle.md
• frontend/Dockerfile

💤 Files with no reviewable changes (1)

• docs/storage-and-lifecycle.md

✅ Files skipped from review due to trivial changes (2)

• docs/DEPLOYMENT.md
• docs/TECHNICAL-DOCUMENTATION.md

---

Walkthrough

Adds two comprehensive documentation files: docs/TECHNICAL-DOCUMENTATION.md (756 lines covering system concept, architecture, backend API, security model, persistence guarantees, frontend behavior, configuration, and operations) and docs/DEPLOYMENT.md (552 lines covering Docker and non-Docker production deployment, secret generation, environment variables, reverse proxy setup, persistence, verification, and operational maintenance). Minor updates include README links, Node.js version pin, environment-mode comments in .env.example, Docker media-prefix plumbing, and removal of an obsolete upgrade note.

Changes

Documentation Addition

Layer / File(s)	Summary
README links, Node version, env.example notes, and Docker plumbing README.md, frontend/README.md, backend/.env.example, frontend/Dockerfile	Root README adds a Documentation section linking to the new technical and deployment guides and removes the Node.js version qualifier; frontend README pins Node.js to 22 with updated nvm command; backend/.env.example adds comments describing ENVIRONMENT/ENV defaults, production classification, and fail-fast startup behavior for missing secrets; frontend/Dockerfile adds NEXT_PUBLIC_MEDIA_PUBLIC_PREFIX build-time argument and env variable alongside NEXT_PUBLIC_BACKEND_URL.
Technical documentation: system concept and architecture docs/TECHNICAL-DOCUMENTATION.md	New file opens with document purpose and companion references; defines the system concept with operational constraint (single concurrent live session per quiz); describes the high-level architecture (static Next.js frontend, single-process FastAPI backend, local filesystem durability, REST/JSON communication, and locally computed timers).
Technical documentation: stack and repository layout docs/TECHNICAL-DOCUMENTATION.md	Documents backend and frontend technology stack with minimum versions; enumerates repository structure including backend modules, routes/services/schemas, scripts, tests, Docker setup, and frontend structure.
Technical documentation: backend routes and API contract docs/TECHNICAL-DOCUMENTATION.md	Specifies backend application composition and mounts; enumerates router endpoints grouped by admin authentication, admin quiz management, admin results, participant play (with availability gating and HTTP status semantics), and media endpoints (with session gating).
Technical documentation: security model and authentication docs/TECHNICAL-DOCUMENTATION.md	Details the single-admin authentication model (bcrypt hash storage and verification), JWT access/refresh token rotation and revocation, password-change invalidation via fingerprinting, cookie and CORS configuration, and startup fail-fast guards; describes abuse protections (Pydantic validation, profanity filtering, image upload safety pipeline, ZIP import safety with rollback, path traversal defenses, per-IP rate limiting, and media gating).
Technical documentation: persistence, concurrency, and frontend docs/TECHNICAL-DOCUMENTATION.md	Details the ACID-like file persistence model (atomic durable writes, serialized quiz writes with in-process locks, live-session TOCTOU avoidance, idempotent submissions, documented lock-free fast paths) and single-worker constraint; covers frontend static-export behavior, build-time configuration baking, in-memory-only admin token handling, and refresh-cookie based recovery.
Technical documentation: configuration, background tasks, testing, and reference docs/TECHNICAL-DOCUMENTATION.md	Provides consolidated environment-variable reference for backend and frontend with build-time baking indicators; documents background purge task scheduling (result retention deletion, stale upload cleanup); summarizes testing, CI workflow, and git hooks; lists intrinsic known limitations; and provides pointers to companion deployment, API, storage lifecycle, and quiz format documentation.
Deployment guide: introduction and prerequisites docs/DEPLOYMENT.md	New file introduces deployment scope and navigation between Docker/non-Docker paths; describes system components (FastAPI backend on port 8000, Next.js static frontend) and request flow; recommends HTTPS reverse proxy; lists runtime prerequisites and dependencies for both deployment modes.
Deployment guide: secrets and environment variables docs/DEPLOYMENT.md	Documents production secret generation for ADMIN_PASSWORD_HASH and JWT_SECRET with Docker-based and non-Docker instructions, including careful quoting guidance for $ characters in bcrypt hashes; enumerates required and optional backend environment variables (secrets gating, CORS origins, cookie flags, data directory, retention/purge, media prefix, rate limiting) and frontend build-time variables with rebuild requirement when backend URL changes.
Deployment guide: Docker and non-Docker paths docs/DEPLOYMENT.md	Details Docker production deployment (building runner images, passing frontend build arguments, external env file configuration, container startup with persistent volumes, single-worker constraint); covers non-Docker path (installing with uv, creating .env and data directory, running Uvicorn without workers, building and copying frontend static output).
Deployment guide: reverse proxy and persistence docs/DEPLOYMENT.md	Specifies reverse-proxy and HTTPS setup (TLS termination, backend route forwarding, media prefix handling, SPA fallback, proxy header configuration); explains data directory layout, backup/restore procedures, and retention semantics tied to RESULT_RETENTION_DAYS.
Deployment guide: operations and checklist docs/DEPLOYMENT.md	Provides deployment verification steps (health endpoint, frontend routing, admin login, end-to-end quiz flow); describes operational maintenance (restart behavior, logs, password-change persistence, update/redeploy); introduces troubleshooting matrix for common configuration failures; supplies final production checklist covering secrets, environment mode, CORS/cookie settings, single-process operation, persistence/backups, build configuration, proxy headers, and health endpoint validation.
Documentation cleanup docs/storage-and-lifecycle.md	Removes obsolete upgrade note regarding migration of in-flight editor staging assets from old to new location.

Sequence Diagram(s)

No sequence diagrams generated for this documentation-focused PR, as it is primarily informational without introducing new executable control flow or multi-component interactions requiring visualization.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• rdest-devs/cogniro#12: Introduces initial Docker and build setup for the frontend Dockerfile that this PR extends with NEXT_PUBLIC_MEDIA_PUBLIC_PREFIX build-time plumbing.

Suggested reviewers

• Ki3mONo

Poem

🐰 Hop hop, the docs have grown so tall,
With deployment guides to help you install!
Secrets hashed, and JWT's just right,
Single-worker backend, running tight.
The rabbit stamps the checklist done —
Production deploy? Already won! 🥕

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding deployment and technical documentation to the project.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch aleksander/rde-89-dodac-dokumentacje-i-instrukcje-deploymentu

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

docs/TECHNICAL-DOCUMENTATION.md (1)

45-45: ⚡ Quick win

Add language identifiers to code fences for markdown consistency.

Lines 45 and 130 contain fenced code blocks without language specifiers. Adding text or plaintext as the language identifier would resolve markdown linting warnings and improve consistency with other code blocks in the document.

💡 Proposed fix to add language identifiers

-```
+```text
                 +-------------------------------+
                 |        Participant /           |

And:

-```
+```text
 cogniro/
   backend/            FastAPI application (Python, managed with uv)

Also applies to: 130-130

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/TECHNICAL-DOCUMENTATION.md` at line 45, Add language identifiers to the
fenced code blocks in the TECHNICAL-DOCUMENTATION.md file. Locate the two code
blocks without language specifiers at lines 45 and 130 (the diagram block
starting with the participant table and the directory structure block with
cogniro/backend/), and change the opening fence from ``` to ```text to add the
language identifier. This resolves markdown linting warnings and maintains
consistency with other code blocks in the document.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@docs/TECHNICAL-DOCUMENTATION.md`:
- Line 45: Add language identifiers to the fenced code blocks in the
TECHNICAL-DOCUMENTATION.md file. Locate the two code blocks without language
specifiers at lines 45 and 130 (the diagram block starting with the participant
table and the directory structure block with cogniro/backend/), and change the
opening fence from ``` to ```text to add the language identifier. This resolves
markdown linting warnings and maintains consistency with other code blocks in
the document.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 15069bf8-8d69-413d-9f60-939ed0923bcb

📥 Commits

Reviewing files that changed from the base of the PR and between d5b9d40 and 540603d.

📒 Files selected for processing (5)

• README.md
• backend/.env.example
• docs/DEPLOYMENT.md
• docs/TECHNICAL-DOCUMENTATION.md
• frontend/README.md

[MichalTheProgrammer]

lgtm