lumendev-invoice

active

LumenDev Invoice

Doc boundary: narrative, decisions, backlog, changelog, and runbooks live in this vault under Projects/lumendev-invoice/. Architecture, data model, API list, feature deep-dives, and testing plans belong in the app repo’s docs/ git submodule (Mode B pillars) once bootstrapped — mirror project-docs-sync.

TL;DR

LumenDev Invoice is a single-service Next.js 16 (App Router) app with MongoDB + Mongoose 9: create and edit invoices, projects, default company settings, mark invoices paid, and export invoice/receipt PDFs client-side via @react-pdf/renderer. Authentication is Auth.js (next-auth v5) with Google OAuth, JWT sessions, and @auth/mongodb-adapter (see [[Projects/lumendev-invoice/changelog/2026-05-17-authjs-shipped|changelog]]; reusable pattern [[Resources/Tech/Auth.js/Auth.js Next.js JWT Google MongoDB adapter pattern|Tech note]]).

Outcome

  • Problem: internal invoice + receipt workflow without a separate receipt entity (receipt = same document, PDF variant).
  • Desired outcome: reliable drafts, paid state, and PDFs aligned with MongoDB as source of truth.
  • Success metric: > TODO(bootstrap): define (e.g. time-to-issue, error rate).
  • Scope (in): see app routes src/app/ and API src/app/api/.
  • Scope (out): > TODO(bootstrap): multi-tenant / row-level auth (shared DB dataset today), payment gateway, email delivery — unless added in repo.

Status

  • Current phase: active development
  • Next milestone: bootstrap docs/ submodule in app repo + keep vault hub in sync
  • Target date:
  • Health: green

Quick Links

  • [[Projects/lumendev-invoice/context/index|Project context]]
  • [[Projects/lumendev-invoice/context/authjs-implementation|Auth.js — Lumen file map]]
  • [[Areas/LumenDev/LumenDev|LumenDev area hub]]
  • [[Resources/Tech/Auth.js/Auth.js Next.js JWT Google MongoDB adapter pattern|Auth.js — evergreen pattern (Tech)]]
  • [[Projects/lumendev-invoice/decisions/index|Decisions]]
  • [[Projects/lumendev-invoice/backlog/index|Backlog]]
  • [[Projects/lumendev-invoice/changelog/index|Changelog]]
  • [[Projects/lumendev-invoice/runbooks/index|Runbooks]]

Open Decisions

  • [[Projects/lumendev-invoice/decisions/adr-2026-05-15-nextjs-mongodb-invoice-stack-snapshot|ADR — Stack snapshot (2026-05-15)]] — accepted (as-built record)

Active Backlog

  • [[Projects/lumendev-invoice/backlog/p2-integrate-waha-due-date-notifications|WAHA due-date notifications]] — p2 / draft
  • [[Projects/lumendev-invoice/backlog/p2-implement-sentry|Implement Sentry]] — p2 / draft

Recent Changes

  • 2026-05-21 — Inbox triage: removed duplicate Inbox/Lumen Invoice app todos again (WAHA + Sentry already on Active Backlog; auth shipped).
  • 2026-05-20 — Inbox triage: deleted stale duplicate Inbox/Lumen Invoice app todos (same three bullets as prior triages; WAHA + Sentry already on Active Backlog; auth shipped).
  • 2026-05-19 — Inbox triage: removed duplicate Inbox/Lumen Invoice app todos again (same bullets as Active Backlog: WAHA, Sentry; auth already shipped).
  • 2026-05-18 — Inbox triage: deleted stale duplicate Inbox/Lumen Invoice app todos (content already on Active Backlog: WAHA, Sentry; auth shipped).
  • 2026-05-17 — Inbox triage: removed duplicate capture Lumen Invoice app todos from Inbox/; WAHA + Sentry remain on Active Backlog; auth is done ([[Projects/lumendev-invoice/backlog/done/p1-implement-authentication|p1 authentication]]).
  • 2026-05-17 — Evergreen Auth.js pattern in [[Resources/Tech/Auth.js/Auth.js Next.js JWT Google MongoDB adapter pattern|Resources/Tech]] for reuse across projects; Lumen file map stays in [[Projects/lumendev-invoice/context/authjs-implementation|context]].
  • 2026-05-17 — Vault — Auth.js implementation map: [[Projects/lumendev-invoice/context/authjs-implementation|context/authjs-implementation]] (files, middleware vs auth.ts, JWT callbacks, requireSession, Mongo adapter). Pairs with app docs/utility/authentication.md.
  • 2026-05-17 — Auth ops/docs: app repo docs/utility/authentication.md (env table, JWT vs adapter, protected routes, secret/OAuth rotation); architecture/API/entities/local-dev cross-links. Vault: [[Projects/lumendev-invoice/runbooks/runbook-auth-failure|runbook — auth failure]].
  • 2026-05-17 — Auth shipped in app repo: Auth.js + Google OAuth, JWT sessions, Mongo adapter, protected APIs and pages. Vault: [[Projects/lumendev-invoice/changelog/2026-05-17-authjs-shipped|changelog]]; backlog [[Projects/lumendev-invoice/backlog/done/p1-implement-authentication|p1 authentication]] → done.
  • 2026-05-17 — Vault inbox triage: added three backlog/ items from Inbox capture Lumen Invoice app todos (auth, WAHA reminders, Sentry).
  • 2026-05-16 — Paid lock + activity log: PUT blocked for paid invoices; Mongo invoiceactivities + GET activity route; Activity panel in editor; UI Details links for paid cards. See [[Projects/lumendev-invoice/changelog/2026-05-16-paid-lock-activity-log|changelog]] and docs/ in LumenDev-Invoice.
  • 2026-05-16 — Roadmap gaps closed in app repo: payment-date validation, mark-paid confirmation UX, /receipt/[id], editor server validation mapping, bulk mark paid, receipts list polish. See [[Projects/lumendev-invoice/changelog/2026-05-16-roadmap-gaps-shipped|changelog]] and docs/ submodule in LumenDev-Invoice.
  • 2026-05-15 — Vault project hub and indexes created; stack snapshot ADR filed. See [[Projects/lumendev-invoice/changelog/2026-05-15-vault-hub-created|changelog]].

Risks & Blockers

  • MongoDB availability local/prod — app expects MONGODB_URI (see app repo AGENTS.md).
  • Auth configuration — AUTH_SECRET, AUTH_URL / AUTH_TRUST_HOST on non-dev hosts, and Google OAuth redirect URIs must be correct or sign-in and session endpoints fail (see AGENTS.md).
  • No automated test suite in app repo yet — regressions caught manually.

Next Actions

  • Manual smoke: invoice editor, mark paid, PDF/receipt flows while signed in — mg
  • Bootstrap docs/ under app repo (architecture/, data-model/, features/, testing/, utility/) and link from this hub — mg
  • Optionally wire docs/ as git submodule and bump vault pointer when tracking matters — mg

Related

  • App repository (local): LumenDev-Invoice (see AGENTS.md, package.json, src/)
  • UX/product flow notes: INVOICE-RECEIPT-FLOW-REPORT.md in app repo (verify claims against code)