# 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.