Skip to content

About

Web interface for MaintMode — maintenance window calendar for engineering teams.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

121 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

maintmode-ui

Web frontend for MaintMode — a maintenance calendar for engineering teams.

MaintMode is where a team schedules planned technical work, sees what it will take down, catches conflicts before two changes collide on the same resource, gets the change approved, and keeps an audit trail of what actually happened.

This repository is the Next.js app. It is also the BFF (backend-for-frontend): the browser never talks to the backend directly, and backend tokens never leave the server.

Self-hosted MaintMode is free and has no seat limit. The hosted SaaS is paid per seat. Both run the same code.

If you want to run MaintMode, start with maintmode-selfhost — it brings up the frontend, the backend, and Postgres together. This README covers developing this repository.

Stack

  • Framework: Next.js 16 App Router (Turbopack)
  • Language: TypeScript, strict
  • UI: React 19 + Tailwind CSS v4 + shadcn/ui (new-york style)
  • Theming: CSS variables with data-theme="dark"|"light" on <html>, managed by a small in-repo provider (src/app/theme-provider.tsx). Dark is the default.
  • Data: TanStack Query v5 — browser → BFF (src/app/api/**) → backend
  • Auth: an encrypted session cookie (jose, src/server/auth/session-cookie.ts); sign-in runs on the backend (OAuth dance, email code, password); tokens stay server-side
  • Tests: Vitest (unit, component, and FE↔BE contract tests)
  • Lint/format: ESLint flat config, Prettier

Local development

npm install
cp .env.example .env.local   # then fill it in — see below
npm run dev                  # http://localhost:3000

Other commands:

npm run lint
npm run typecheck        # tsc --noEmit; covers test files, which the build does not
npm run test             # unit + component tests
npm run test:boundaries  # static import-boundary check
npm run test:contracts   # FE↔BE contract tests against captured wire fixtures
npm run build
npm run test:bundle      # heavy deps must not be eagerly reachable (needs a build)
npm run verify           # all of the above, in that order

You also need the backend running and reachable at MAINTMODE_API_BASE_URL. The easiest way to get one is the selfhost compose stack.

Required environment

Four variables are mandatory. src/shared/config/auth-config.ts validates them at module load, and throws when any is missing or malformed:

Variable Notes
MAINTMODE_AUTH_SECRET at least 32 characters — openssl rand -hex 32
MAINTMODE_APP_BASE_URL e.g. http://localhost:3000; must be a valid http/https URL
MAINTMODE_AUTH_PUBLIC_BASE_URL the auth backend as the browser reaches it; see the warning below
MAINTMODE_BACKEND_S2S_TOKEN the BFF's client credential; must equal the backend's s2s.maintmode-ui.secret — see below

Without these, nothing starts at all — including /login. The validation runs when the config module is imported, not when someone tries to sign in, so the failure is a startup crash rather than a broken login button. If the app dies immediately on boot, check these first.

MAINTMODE_AUTH_PUBLIC_BASE_URL is not MAINTMODE_AUTH_API_BASE_URL. The first is followed by the user's browser; the second is used server-to-server and is a container name in the dev and local deployments (http://caddy:3000/auth). Setting the internal value here passes validation and then fails at the first click on a provider button, with nothing in this app's logs — the request never reaches it. Include any gateway path prefix: http://localhost:9000/auth, not http://localhost:9000.

MAINTMODE_BACKEND_S2S_TOKEN must equal the backend's s2s.maintmode-ui.secret. It goes out as X-S2S-TOKEN (with X-S2S-APPNAME: maintmode-ui) on every request to the auth backend, which refuses its token endpoints without it (RUK-311). At least 32 characters, printable ASCII, no whitespace. A value that passes validation but differs from the backend's does not crash anything: every sign-in fails as "invalid credentials", and signed-in users get 503 once their access token needs a refresh — their sessions are kept, and recover as soon as the values match. The server log then has an ERROR line naming this variable — look for invalid_client. Update the backend and this app together when you rotate it.

Backend wiring (see .env.example for the full annotated list):

MAINTMODE_API_BASE_URL=http://localhost:9000/maintmode
MAINTMODE_AUTH_API_BASE_URL=http://localhost:9000/auth   # empty → falls back to the above
MAINTMODE_API_TIMEOUT_MS=10000

Two local-only flags, both ignored when NODE_ENV=production:

  • MAINTMODE_DEV_AUTH_BYPASS=true — adds a dev-only "login as role" block to /login that runs the backend exchange with a placeholder id_token.
  • MAINTMODE_DISABLE_AUTH_GUARD=1 — skips the auth gate in src/proxy.ts, useful while wiring OAuth end-to-end.

Neither can be turned on in a production build; that is deliberate. See SECURITY.md.

Sign-in methods

Two kinds of sign-in exist. Both are configured on one admin page, Authentication (/admin/authentication), which also shows what /login currently offers.

Built-in methods — email + password and a one-time code sent by email — are switched on and off by an administrator under Authentication → Built-in methods. A fresh install has email + password on and email code off. Turning a method off removes it from /login; turning email + password off also removes "Forgot password?", which lives inside the password form.

Providers — Google, GitHub, or any OpenID Connect IdP as "Custom OIDC" — are created by an administrator under Authentication → Sign-in providers (SSO). Every provider that is enabled and healthy appears on /login and on invitation pages by its display name; nothing in this app lists them by hand.

It is legitimate to run with every built-in method off (SSO only). But with no built-in method and no working provider, nobody can sign in except through break-glass; the Authentication page warns when that is the case. Email code also needs the Email transport under Integrations, and the page says so when it is missing or off.

Setting up a sign-in provider

This app is not an OAuth client. The backend runs the whole dance and holds the client secret; the provider button redirects the browser to the backend, and /auth/oauth/callback here receives the result. On this side the only setting is MAINTMODE_AUTH_PUBLIC_BASE_URL (see above).

1. Arm the dance on the backend. Three values in the backend's app.config.yaml, all required — leave any of them empty and the dance routes do not register, so every provider button leads to a 404:

  • app.frontend_url — the external URL of this app. The dance's success redirect, carrying a live one-time code, is built from it. The prod sample ships https://maintmode.example.com: left as it is, every completed sign-in hands an auth code to a domain you do not control, and nothing fails to tell you.
  • app.oauth_callback_path — this app's receiver route, /auth/oauth/callback. The two must agree; the shipped values already do.
  • app.oauth_cookie_path — the external path prefix of the backend's OAuth routes as the browser sees them (/auth/api/v1/login/oauth behind the shipped gateway).

2. Create the provider in the app. Authentication → Sign-in providers (SSO) → Set up. You supply the client ID, the client secret and the redirect URI; for Google and GitHub the deployment fills in the rest (the preset catalog under oauth_providers.presets in the backend config). The redirect URI is the backend's external callback:

<MAINTMODE_AUTH_PUBLIC_BASE_URL>/api/v1/login/oauth/<provider>/callback

where <provider> is google, github or custom — for example https://maintmode.example.com/auth/api/v1/login/oauth/google/callback.

3. Register the same redirect URI with the provider (Google Cloud Console, the GitHub OAuth app, your IdP). A mismatch is rejected on the provider's side and never appears in any of our logs.

The row's status on the Integrations screen says whether the backend has picked the provider up ("Active"), has not yet ("Not picked up yet"), or cannot read its secret.

Accepting an invitation needs a provider. An invitation is accepted by signing in through a provider, which applies the invitation's roles inside the dance; the invitation page offers every enabled provider. On an instance with no provider, invitations cannot be accepted — the page says so and the invitation stays valid.

First login (bootstrap admin)

On a fresh installation the first person to sign in becomes the administrator. This is first-login-wins: there is no invite, no claim code, and no lock on the window.

Until a provider is set up (above), sign in with email + password, which is on by default.

Sign in yourself before the instance is reachable from anywhere else. If a stranger reaches your /login first, they get the admin account. Bring the app up on a private network or behind your own access control, complete your first sign-in, and only then open it up. Every subsequent user joins by invitation.

Architecture

browser ──► BFF route handlers (src/app/api/**) ──► backend API

The browser must call backend systems through the BFF. Browser modules must not import src/server/**. Backend access and refresh tokens live in the encrypted httpOnly session cookie and are read only from server-only code; the browser never receives them. A backend 401 is normalized and turns into a redirect to /login?next=<current path>.

Layers under src/:

Path Owns
app/** routes, layouts, route shells
app/api/** BFF entrypoints
server/backend/** backend clients, DTO contracts, error normalization
server/auth/** session tokens, backend token exchange
domain/** UI-agnostic models and rules (no React, no Next.js)
features/** flow-specific composition, hooks, queries, feature UI
shared/ui/shadcn/** generated shadcn primitives (vendored layer)
shared/ui/domain/** hand-rolled cross-feature components
shared/config/** runtime config parsing (environment reads stay server-side)

npm run test:boundaries enforces these statically. AGENTS.md has the full rules, including the styling contract.

Contract tests

Five FE↔BE drift incidents reached production because nothing executed the BFF proxy in a test. As a result, every new BFF route ships with a contract test, response fixtures are captured (npm run fixtures:refresh) rather than hand-written, and mapper stubs are registered in docs/contract-gaps.md — an executable registry whose test fails both on an unregistered stub and on a gap that has since closed, so stale rows get deleted instead of rotting. See CONTRIBUTING.md.

Bundle budgets

node scripts/measure-bundle.mjs prints per-route eager JS and CSS from the last build — the before/after instrument for any change that moves bundle weight. npm run test:bundle is the CI guardrail built on the same manifests: it fails when a heavy dependency (FullCalendar, luxon, cmdk, react-day-picker) becomes reachable through a route's synchronous import graph. It is one-directional by design and cannot see a dependency that is wrongly deferred, so its allowlist marks permanent exceptions explicitly.

Contributing

See CONTRIBUTING.md. Security reports go through SECURITY.md, not public issues.

License

Licensed under the GNU Affero General Public License v3.0. See LICENSE.

AGPL-3.0 means you are free to run, study, modify, and share this software. If you run a modified version as a network service, you must offer that service's users the corresponding source of your modified version.

About

Web interface for MaintMode — maintenance window calendar for engineering teams.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages