Developer reference

Technical Specifications

A complete reference for CoreOps-Forge — architecture, data model, integrations, security and deployment. Built on CoreOps-Base, with additional layers for project management, GitHub integration and a token-authenticated REST API.

Next.js 15React 19TypeScriptHonoPostgreSQLTailwind CSSDockernginx

Application Architecture

A single Next.js deployment that serves the UI, the REST API, and the data layer — server components for fetching, client components only where interactivity demands it.

Next.js 15 with React 19 and TypeScript — server components for data fetching, client components for interactivity
Hono REST API server running alongside Next.js at /api/* and /v1/*
PostgreSQL database — connect to a local instance, Docker Compose service, or any hosted provider
Tailwind CSS with dark and light theme support
Built on CoreOps-Base for authentication, RBAC, mail, backups, and system logging

Projects & Tickets

A multi-project workspace where every ticket carries full type, status, and relationship metadata, plus field-level history for complete traceability.

Multi-project workspace with per-project membership and roles: owner, admin, member, and viewer
Ticket types: feature, bug, maintenance, infrastructure change, incident, and technical debt
Ticket statuses: backlog, todo, in_progress, in_review, done, cancelled, and pending_approval
Field-level history on every ticket change — always see who changed what and when
Parent/child ticket relationships for hierarchical work breakdown
Ticket labels, time tracking with timers, file attachments, and linked infrastructure resources
Bulk status transitions and priority updates across multiple tickets at once

Sprints

Time-boxed iterations with an enforced single-active-sprint model and automatic backlog reconciliation on close.

Planning, active, and completed sprint lifecycle — one active sprint per project enforced
Incomplete tickets automatically returned to the backlog on sprint completion
Sprint progress tracked as done/total ticket counts
REST API endpoints for full sprint management

Kanban Boards

One configurable board per project, mapping columns to ticket statuses with WIP limits to keep flow visible and controlled.

One board per project with configurable columns mapped to ticket statuses
Drag-and-drop column assignment for tickets
WIP limits per column to control flow and surface bottlenecks
Done columns configurable for automatic ticket closure

GitHub Integration

Bi-directional sync: create branches outbound via the GitHub API, and ingest verified webhook events inbound, auto-linked to the tickets they affect.

Per-project repository linking — multiple repositories supported per project
Outbound branch creation via GitHub API using a stored personal access token
Inbound webhooks for push, pull_request, and deployment_status events verified with HMAC-SHA256
Auto-linking via closes/fixes/resolves #N keywords in commit messages and PR titles
Deployment state tracking linked to tickets via commit SHA
Full webhook delivery log for debugging and audit

Approval Workflows

A configurable gate that holds tickets in pending_approval until a designated approver signs off — with mandatory rejection notes and a retained decision history.

Approval rules configurable per project per ticket type
pending_approval status gate before tickets can progress
Approvers notified on submission; approve, reject, or delegate actions available
Mandatory notes required on rejection
Full approval history retained on each ticket

Infrastructure Resources

A per-project registry of infrastructure components — servers, databases, services, and networks — with ownership, criticality, and dependency tracking.

Resource types: server, database, service, network, storage, and application
Environment classification: production, staging, development, and DR
Criticality levels: critical, high, medium, and low with owner assignment
Resource dependencies — map which resources rely on others
Link resources directly to tickets for impact analysis
Resource status tracking: active, maintenance, deprecated, and decommissioned

Maintenance Windows

Plan, schedule, and communicate maintenance events at the project level, with resource and ticket linking for full impact visibility.

Create and schedule maintenance windows with start/end times and descriptions
Link affected infrastructure resources and related tickets to each window
Calendar view of upcoming and past maintenance events
Active maintenance windows surfaced automatically on the customer portal status page
Cancel windows with a reason — cancellation is recorded in the audit trail

Customer Portal

A per-project public-facing portal where customers can submit requests, track their tickets, vote on features, and view live incident and maintenance status.

Per-project portal with self-registration or invite-only access (configurable)
Customers submit requests that become tickets in the project backlog
Request tracking — customers see status updates and can add comments
Public roadmap with voting — customers upvote feature requests
Live status page — shows active incidents and upcoming maintenance windows
Email notifications to customers on ticket status changes
Admin customer account management: view, enable/disable, delete accounts

Analytics & Reports

Project-level performance metrics and exportable reports giving visibility into team throughput, delivery speed, and workload distribution.

Sprint velocity tracking — done ticket counts per sprint over time
Cycle time and lead time with p50 / p85 / p95 percentile breakdown
Flow efficiency ratio — active time vs wait time in the ticket lifecycle
Team performance report: throughput, cycle time, and workload per member
Built-in ticket reports: status breakdown, sprint summary, label distribution
Export any report as CSV or PDF from the admin panel

Data Migrations

First-class import tools for Jira Cloud and Linear, with dry-run validation and full field mapping so migrations are safe and predictable.

Jira Cloud import — projects, tickets, comments, attachments, labels, and sprints
Linear import — teams, issues, comments, labels, and cycles
Dry-run mode previews what will be imported before committing
CSV data validation tool for pre-import data quality checks
Admin-only tool — accessible from Tools in the navigation

REST API

A first-class, token-authenticated API surface covering every resource, with rate limiting, an OpenAPI schema, and a full request log.

Hono-based REST server at /api/* and /v1/*
Personal access token (PAT) authentication via Bearer header
Project-scoped endpoints for tickets, sprints, boards, members, and git events
Rate limiting per IP address
OpenAPI schema available for integration and tooling
API enable/disable toggle in system settings; full request log

Authentication & Security

Defence in depth from the CoreOps-Base foundation — encrypted sessions, TOTP MFA, lockouts, IP allowlisting, CAPTCHA, and hardened HTTP headers.

Encrypted cookie sessions (iron-session) with bcrypt password hashing
TOTP MFA with QR setup, 10 single-use backup codes, and admin disable capability
Configurable per-account lockout after failed login attempts (count and duration via admin panel)
In-memory IP-based rate limiting on login, registration, and password-reset actions
Admin panel IP allowlist — restrict access to CIDR ranges or exact IPs
Cloudflare Turnstile CAPTCHA on public-facing forms (test key fallback in dev)
Session invalidation on password change — all other devices are logged out
HTTPS enforcement headers including HSTS, CSP, and X-Frame-Options
Active session management — view and terminate sessions from the admin panel

Database

PostgreSQL with idempotent migrations that run automatically on startup, in-memory settings caching, and built-in backup/restore.

PostgreSQL — schema initialised automatically on startup with idempotent migrations
Schema initialised and migrated automatically on startup
Idempotent migrations safe to run repeatedly without side effects
Settings cached in memory with lazy reload for performance
Full database backup and restore available from the admin panel

Deployment

Container-first delivery: a hardened Docker image, Compose with persistent volumes, an nginx TLS front door, and runtime-configurable settings.

Docker container with non-root user and minimal production footprint
Docker Compose with persistent volumes for database, uploads, and backups
nginx reverse proxy with rate limiting and TLS termination
All settings configurable at runtime via the admin panel — no restart required
Custom JavaScript injection for analytics snippets and tag managers (System → Custom Scripts)
Outbound webhook notifications for auth and system events with delivery log

list tickets · REST API200 OK

# Authenticate with a personal access token
curl https://your-host/v1/projects/forge/tickets \
  -H "Authorization: Bearer $FORGE_PAT"

# → 200 OK
{
  "data": [{ "id": "FORGE-211", "status": "in_progress" }],
  "page": 1, "total": 42
}