| name | inboxbridge-backend-change |
| description | Use when changing the Quarkus backend, Flyway schema, mailbox import logic, auth/session services, or REST endpoints in InboxBridge. Focuses on backend architecture, transactional boundaries, security invariants, and backend validation. |
InboxBridge Backend Change
Start with docs/ARCHITECTURE.md, CONTEXT.md, and the affected packages under src/main/java.
If the task is specifically about backend architecture quality, Quarkus / Java
best practices, folder structure, or package-boundary reviews, also load
../inboxbridge-quarkus-best-practices/SKILL.md.
Backend invariants
- Keep Quarkus as the system of record for auth, OAuth, sessions, secret handling, and polling state.
- For provider OAuth callbacks, keep the backend as the secure callback and
state-validation authority, but prefer frontend-owned callback UI over
embedded Java HTML when the user-facing flow needs richer copy, translation,
or visual consistency.
- Preserve the hard boundary that one user's source mail must never import into another user's destination mailbox.
- Preserve the newer destination-aware runtime model: checkpoint reuse, dedupe visibility, and source diagnostics all key off the resolved destination mailbox identity rather than the source alone.
- Preserve encrypted-at-rest handling for UI-managed passwords, refresh tokens, and related secrets.
- Avoid fallback paths that weaken secure storage or browser OAuth exchange requirements.
- When async polling workers touch repositories, keep transactional boundaries explicit. Virtual-thread workers do not inherit the original request context.
- Remember that authenticated SSE endpoints also pass through database-backed auth/session filters, so blocking execution and transactional boundaries matter for
/api/poll/events, /api/admin/poll/events, and related live-poll endpoints.
- Keep the current source-diagnostics plumbing coherent when changing polling state or summaries: admin and user source views now surface destination identity, per-folder checkpoints, throttle state, IMAP IDLE watcher health, and recent poll audit details through dedicated DTOs/services.
- Respect the existing package split:
config, domain, dto, persistence, service, web.
When to add stronger coverage
- Polling, mailbox import, dedupe, or destination routing changes: add or update backend tests, and prefer GreenMail-backed integration coverage for real mailbox I/O paths.
- Auth, passkeys, sessions, CSRF, or OAuth changes: cover failure cases and security regressions, not only happy paths.
- Schema or persistence changes: add the Flyway migration plus the tests or code paths that prove the new shape is used.
Validation
- Backend-focused pass:
mvn -q test
- Prefer a focused Maven test command first when the changed area is narrow.
- If the task touched runnable services, finish with
docker compose up --build -d unless the user said not to.
Docs to update when relevant
