Developer reference

Technical Specifications

A developer-focused breakdown of CoreOps-Base's architecture, subsystems and capabilities — a reference for engineers evaluating, extending or deploying the platform.

Next.js 15React 19TypeScriptPostgreSQL 16Tailwind CSSPrometheusDockernginx

Application Architecture

A type-safe Next.js 15 application with a clean public/protected split and server-side rendering — interactivity layered on only where it's needed.

Built on Next.js 15 with React 19 and TypeScript for a modern, type-safe foundation
Clean separation between public (unauthenticated) and protected (authenticated) routes
Server-side rendering for fast initial loads; interactive elements handled client-side
Form submissions processed server-side — no separate API calls needed from the UI
Tailwind CSS with a comprehensive component library for a consistent, accessible UI
Dark and light theme support with server-side resolution — no flash on page load
Built-in analytics support for production environments

Authentication

Encrypted cookie sessions, hashed credentials and TOTP MFA — with every protected navigation verified server-side.

Encrypted cookie-based sessions — no server-side session store required
Passwords hashed using industry-standard algorithms before storage
Sessions automatically invalidated when a user changes their password
Configurable session lifetime from 1 hour up to 90 days via admin settings
New accounts start inactive — users activate via a time-limited email link
Accounts temporarily locked after too many failed login attempts (configurable)
Time-based one-time password (TOTP) MFA with QR code setup and 10 backup codes
Access to protected pages always verified server-side on every navigation

Authorisation & RBAC

Three built-in groups and a policy engine that decides, per role, exactly which resources and actions are permitted.

Three built-in groups: Admin, User, and Guest — each with distinct access levels
Admins have full platform access; other groups are restricted to assigned permissions
Policy engine: define which roles can access which resources and perform which actions
Default group for new self-registrations is configurable
MFA setup is always user-initiated — admins cannot enable it on behalf of a user
MFA enforcement can be switched on globally; users who have not completed setup are blocked after a configurable grace period (in days) expires — a grace period of zero enforces immediately on next login
Blocked users are shown a dedicated page with a direct link to complete MFA setup — the profile page remains accessible so they can resolve it without admin intervention
The admin group is a protected system group and cannot be deleted

User Management

Admin-created or self-service accounts with invite flows, full sign-in history and verified email changes.

Accounts can be created by admins or via self-registration (can be enabled or disabled)
Invite flow: admin creates the account, activation link emailed, user sets their own password
Admins can enable or disable accounts, change groups, reset passwords, and disable MFA
Full sign-in history per user: logins, failures, lockouts, and MFA events
Email address changes require verification — new address confirmed before it takes effect
Users manage their name, email, password, and display theme from their profile
Per-user API access tokens available when the REST API feature is enabled

Rate Limiting & Lockout

Per-IP throttling and persistent account lockout across every sensitive endpoint, tunable without code changes.

Automatic rate limiting per IP address on login, registration, password reset, MFA, and contact
All thresholds are adjustable from the admin settings — no code changes needed
Accounts lock automatically after a configurable number of consecutive failed password attempts
Lockout state is stored persistently — survives server restarts
Works alongside network-level rate limiting at the reverse proxy layer
CAPTCHA protection on public-facing forms to block automated submissions

Email

Runtime-configurable SMTP with built-in templates and fully logged, non-blocking delivery.

SMTP email delivery with settings fully configurable at runtime via the admin panel
Change your mail provider, credentials, or sender address without restarting the server
Five built-in templates: account welcome, password changed, password reset, email update, and test
Email failures never interrupt user-facing actions — delivery is handled in the background
Every email attempt is logged — always see what was sent, to whom, and whether it succeeded
Send a test email directly from admin settings to verify your configuration

REST API

A permission-mirrored REST surface you can toggle at runtime, with per-user tokens for external tooling.

Full REST API available at /api/* for programmatic and third-party integrations
API access toggled on or off from admin settings — no deployment required
All API requests require authentication; permissions mirror those of the web interface
Allowed origins configurable for cross-origin access
Full request validation on all endpoints
Per-user API access tokens for external tooling and automation

Monitoring & Metrics

A Prometheus-compatible metrics endpoint with runtime and request instrumentation, ready for any OpenMetrics stack.

Prometheus-compatible metrics endpoint at /api/metrics — ready to scrape with any standard collector
Node.js runtime metrics included by default: GC pause, heap usage, event loop lag, CPU usage, and process uptime
API request counter tracks total requests broken down by HTTP method, route, and response status
API request duration histogram measures response time in milliseconds across a spread of latency buckets
Route labels use matched route patterns rather than raw paths — keeps metric cardinality low regardless of the number of unique resource IDs
Endpoint protected by Bearer token authentication, managed through the platform's RBAC policy engine
Metrics are only exposed when the REST API feature is enabled — disabled by default
Compatible with Prometheus, Grafana, and any other OpenMetrics-compatible monitoring stack

Database

PostgreSQL 16 with automatic schema initialisation, pooled connections and one-command backup and restore.

PostgreSQL 16 database — connect to a local instance, Docker Compose service, or any hosted provider (Neon, Supabase, Railway)
Connection pool managed automatically — handles concurrent requests across multiple Next.js workers without configuration
Schema initialised automatically on startup — no manual migration steps or CLI tools required
Fast-path migration detects existing databases and applies only incremental changes, skipping the full schema block
Runtime settings cached in memory for performance; live values always available for critical checks
Default data seeded safely on every startup — idempotent inserts mean no risk of duplicating existing records
Full database backup via pg_dump and restore via psql available from the admin panel

Logging & Observability

Four dedicated, non-blocking logs covering authentication, email, system processes and public traffic.

Authentication log: every login, logout, failure, lockout, rate limit event, and MFA attempt
Email log: every send attempt with recipient, delivery status, and full message content
System log: platform-level events across backup, API, settings, email, and calendar processes
Traffic log: every visit to public pages — path, IP address, browser, referrer, and timestamp
All log writes are non-blocking — a logging failure never affects the primary operation
Log pages are paginated and filterable by event type, process, or status

Configuration & Feature Flags

Database-backed settings and feature flags that take effect immediately — no restart, no redeploy.

All platform settings stored in the database — changes take effect immediately without a restart
Feature flags control: self-registration, password reset, MFA, and API access
Configurable landing page for unauthenticated visitors: login, welcome, or maintenance
Session lifetime configurable from 1 hour to 90 days
Maximum file upload size configurable
Default group for new users is configurable
Password complexity rules: minimum length, uppercase, lowercase, numbers, and special characters
Application name, description, and SEO metadata all editable from the admin panel

Security

Globally-applied headers and browser-permission lockdowns that ship on by default — no per-page configuration.

Clickjacking protection — prevents the platform being embedded in another website
MIME-type sniffing prevention — browsers honour declared content types
Referrer information restricted on cross-origin requests to limit data leakage
Camera, microphone, and geolocation browser access disabled by default
HTTPS enforced after first secure connection — valid for 1 year including subdomains
Content Security Policy restricts which scripts, styles, and resources the page may load
All security headers applied globally — no per-page configuration needed

Deployment

Containerised with a tuned nginx reverse proxy, persistent volumes and TLS termination at the edge.

Containerised with Docker — production-ready image with a minimal footprint and non-root user
Postgres runs as a separate service in Docker Compose; upload and backup directories mounted as persistent volumes
nginx reverse proxy configuration included with pre-tuned rate limiting for auth and API routes
TLS termination at the proxy layer — HTTPS enforced before requests reach the application
Cloudflare Turnstile CAPTCHA protects registration, password reset, and the contact form
Two environment variables required to activate production CAPTCHA (site key + secret key)

scrape /api/metrics200 OK

# Prometheus-compatible, Bearer-token protected
curl -H "Authorization: Bearer $TOKEN" https://your-host/api/metrics

# HELP api_request_duration_ms request latency
# TYPE api_request_duration_ms histogram
api_requests_total{method="GET",route="/api/users",status="200"} 1284
nodejs_eventloop_lag_seconds 0.0021