rhl-lieferscheine/Docs/decisions.md

Decisions Log

Decisions extracted during Codex onboarding on 2026-04-16. These reflect the current state of the project as understood from the approved onboarding summary and owner interview.

Decision: Next.js App Router on a JavaScript-only stack

• Status: adopted (pre-Codex)
• Date: pre-onboarding
• Context: The project is maintained by a single developer and aims to deliver an internal tool quickly without adding unnecessary platform overhead.
• Decision: Build the application on Next.js 16 App Router, React 19, JavaScript/JSX, Tailwind CSS 4, and MongoDB/Mongoose.
• Tradeoffs: The stack stays lightweight and productive, but it relies on discipline rather than TypeScript-level static guarantees.

Decision: Cookie-based JWT sessions with branch-aware RBAC

• Status: adopted (pre-Codex)
• Date: pre-onboarding
• Context: Branch users must be restricted to their own documents, while privileged roles need broader operational access.
• Decision: Use a signed JWT session cookie (auth_session) together with RBAC roles branch, admin, superadmin, and dev.
• Tradeoffs: The model matches the business structure well, but it makes HTTPS, auth hardening, and careful permission checks operationally important.

Decision: Model the product around the existing NAS folder hierarchy

• Status: adopted (pre-Codex)
• Date: pre-onboarding
• Context: Delivery note PDFs are scanned outside the application and written directly into branch/year/month/day folders on the NAS.
• Decision: Keep explorer navigation and path-based document access aligned with the NAS hierarchy instead of introducing an additional document abstraction layer.
• Tradeoffs: The application stays close to the real storage model, but it is tightly coupled to path conventions and NAS availability.

Decision: Keep explorer and search navigation URL-driven

• Status: adopted (pre-Codex)
• Date: pre-onboarding
• Context: The owner wants predictable navigation, shareable deep links, and a simple state model.
• Decision: Treat the URL as the source of truth for explorer and search state.
• Tradeoffs: Deep-linking stays straightforward, but UI state changes must stay carefully synchronized with routing behavior.

Decision: Keep the product scope intentionally pragmatic

• Status: adopted (pre-Codex)
• Date: pre-onboarding
• Context: The application should solve the core delivery-note retrieval problem without overwhelming users or stretching a one-developer project.
• Decision: Focus on login, scoped access, explorer, search, PDF open, profile/password management, and privileged user management. Keep large dashboards, saved searches/bookmarks, and an in-app PDF viewer out of scope unless explicitly re-approved.
• Tradeoffs: The product stays lean and easier to ship, but some convenience features are intentionally deferred or dropped.

Decision: Treat Qsirch as required for the target environment

• Status: adopted (pre-Codex)
• Date: pre-onboarding
• Context: The current v1 search experience is too slow without indexed search, and v2 is expected to fix that.
• Decision: Treat Qsirch as a required production-facing dependency rather than an optional enhancement.
• Tradeoffs: Search performance improves, but the rollout depends on Qsirch availability, credentials, and operational setup.

Decision: Integrate Codex artifacts into the existing Docs/ tree

• Status: approved
• Date: 2026-04-16
• Context: The repository already contains established documentation in Docs/, and Docs/frontend-ui.md currently has local changes that must not be disturbed.
• Decision: Write Codex onboarding artifacts into Docs/ and leave existing project documentation untouched unless explicitly requested.
• Tradeoffs: Historical and Codex-generated documentation now coexist in one directory, so future updates must stay disciplined to avoid drift.