OrchestrAD/docs/DesignSpecificationTemplate.md

Generic Application Framework Specification

1. Purpose

This document defines the standard framework, architecture, operational patterns, security model, build conventions, and UI expectations that should be reused across future applications.

It is intentionally product-agnostic.

The goal is to provide a reusable implementation blueprint so new applications can be built consistently without re-deciding the same foundational concerns every time.

This framework should be treated as the default starting point for all future applications unless a project explicitly requires justified deviations.

---

2. Core Principles

1. One strong foundation, many apps

   • Foundational concerns should be solved once and reused.

2. Centralization over duplication

   • Shared logic for auth, logging, configuration, error handling, build/versioning, persistence patterns, API behavior, and UI patterns must be centralized.

3. Operational clarity first

   • Logs, health, configuration, and runtime behavior must be easy to understand and operate.

4. Secure by default

   • Secrets, sessions, tokens, credentials, and privileged actions must be designed with least privilege and strong defaults.

5. Build in the correct order

   • Foundations must be implemented before domain features to avoid rework.

6. Cross-platform by default

   • Applications should run on Windows, macOS, Linux, and Docker unless the product clearly requires otherwise.

7. API-first and UI-friendly

   • Backend capabilities should be accessible through a clean API, and the UI should consume those capabilities without embedding domain logic into components.

8. Future-proofing without overengineering

   • The architecture should support reasonable growth without requiring premature complexity.

---

2.1 Implementation Configuration Questions

This framework exposes a small set of configurable implementation choices that each concrete application must answer. The questions are written as structured blocks so an AI implementer (Claude Code, Augment, or similar) can read them, honor the answers, and apply the correct implementation sections.

For each application, copy the blocks below into the application's own specification and fill in the answer field. If no override is provided, the default is assumed.

Question: Embed the built web UI into the backend binary?

id: embed_ui_in_binary
question: Should the built web UI be embedded into the backend binary so a single binary ships the full product (API + UI)?
allowed_values: [yes, no]
default: yes
answer: yes

Behavior contract:

• When answer: yes (framework default):
  • The frontend must be buildable as a fully static export and placed in a deterministic output directory (e.g. frontend/out/).
  • The backend must embed that directory via //go:embed and serve it from its own HTTP server.
  • The backend router must mount the embedded UI on all non-API routes as an SPA fallback so deep links resolve to index.html, while /api/v1/*, /healthz, and other reserved routes continue to be served by their handlers.
  • The build pipeline must build the frontend before the backend and must fail clearly if the expected UI output directory is missing or empty.
  • The single produced binary must be sufficient to run the full product without any separate web server, Node.js runtime, or static asset host.
• When answer: no:
  • The backend must not embed any frontend assets and must not serve UI routes.
  • The frontend is deployed as an independent artifact (container, static host, CDN, etc.).
  • CORS must be configured explicitly for the chosen frontend origin(s); localhost must remain allowed for development.

Cross-references: see Section 3.2 (Frontend), Section 3.4 (UI Delivery Model), Section 5.2 (Embedded Resources), and Section 16 (MVP Acceptance Template).

---

3. Standard Technology Direction

3.1 Backend

Preferred backend language: Go

Reasons:

• Strong cross-platform support
• Excellent fit for long-running services and CLIs
• Simple deployment model with single binaries
• Strong standard library
• Good concurrency model
• Mature ecosystem for API servers, background processing, logging, and packaging

Recommended backend stack:

• HTTP router: Chi
• OpenAPI / Swagger: OpenAPI-first generation or swaggo
• Database access: sqlc + database/sql by default
• Migrations: golang-migrate
• Logging: slog with lumberjack for rotation
• Scheduling: robfig/cron where recurring background jobs are needed
• Password hashing: argon2id
• Encryption: AES-GCM with centralized key handling
• Config loading: environment variables first, optional config file support

3.2 Frontend

Preferred frontend direction:

• Next.js
• TypeScript
• Material UI
• Tailwind CSS
• TanStack Query
• react-hook-form
• Zod

Preferred UI template baseline:

• Spike-NextJS-PRO-Template should be considered the default dashboard/admin UI foundation
• It should be brought in via subtree and adapted, not copied ad hoc into each project

Static-export compatibility:

• Frontends built on this framework should remain compatible with Next.js static export (output: "export") so the embedded-binary delivery model in Section 3.4 stays viable.
• Avoid server-only Next.js features (Route Handlers, getServerSideProps, server-only next/headers usage, per-request dynamic rendering) unless a specific application explicitly opts out of the embedded delivery model.
• Runtime-dependent values (API base URL, feature flags) should be resolved at runtime from the current window origin or an application-provided config endpoint, not hard-coded at build time.

API base URL contract (embedded-binary mode):

• The compiled frontend bundle must contain no hardcoded scheme, host, or port for the backend API. Any fallback used when window is undefined during SSR/prerender (for example, a default http://localhost:8080) will be captured into the static chunks and will leak into production bundles; this is forbidden.
• The API client must resolve the base URL in this priority order:
  1. A build-time override such as NEXT_PUBLIC_API_BASE_URL if explicitly set.
  2. window.location.origin at runtime in the browser.
  3. An empty string when window is unavailable (SSR/prerender), in which case the client must emit a relative URL (path?query) so the browser resolves it against the real origin at fetch time.
• The same compiled bundle must work under any scheme/host/port combination the binary is served on, including behind a reverse proxy that rewrites the public URL.

Frontend route layout:

• Adopted UI templates frequently ship demo route layouts (for example, /auth/auth1/login, /dashboards/demo, etc.) that reflect the template's variant showcase rather than a shipped product. Before committing a template's routes, flatten them to a single, human-memorable layout (for example, /login, /, /users) and update every header link, sidebar entry, auth context redirect, and guard redirect to match.
• Doing this flattening in the first frontend commit avoids repeated cross-cutting rewrites later once every screen has been wired to the template's original paths.

3.3 Data Layer

Preferred default database:

• SQLite for single-node applications and early-phase products
• WAL mode enabled by default
• Foreign key enforcement enabled
• Migration support required from day one

Future portability:

• Repositories and schema patterns should be designed so migration to PostgreSQL or another relational database is possible later if needed

3.4 UI Delivery Model

The UI delivery model is governed by the embed_ui_in_binary question in Section 2.1. The framework default is yes: the built UI ships inside the backend binary, so a single artifact hosts the full product.

Embedded-binary mode (default)

• The frontend must be buildable as a fully static export and must produce a deterministic output directory (e.g. frontend/out/).
• The backend must embed that directory via //go:embed behind a small assets package.
• The HTTP server must:
  • continue to serve API routes (e.g. /api/v1/*) and operational routes (e.g. /healthz) from their existing handlers
  • serve static assets from the embedded filesystem for all other routes
  • implement SPA fallback: GET requests for non-API routes that do not match a static file must return index.html with HTTP 200 so client-side routing works for deep links
  • serve assets with appropriate Content-Type and long-lived cache headers for hashed/chunked assets
• The build pipeline must build the frontend first, then the backend. If the expected UI output directory is missing or empty when building the backend, the build must fail with a clear, actionable error.
• The single produced binary must fully host the product. No separate Node.js runtime, web server, or static file host is required for normal operation.
• Development ergonomics are unaffected: running the frontend dev server against the backend API over CORS remains acceptable during development, as long as production builds use the embedded flow.

Separate-deployment mode (embed_ui_in_binary: no)

• The backend must not embed frontend assets and must not serve UI routes.
• The frontend is built and deployed as an independent artifact (container, static host, or CDN).
• CORS must be configured explicitly for the frontend origin(s); localhost must remain allowed for development.
• Version reporting must still ensure the UI and backend report the same version at runtime so operators can verify they are paired correctly.

---

4. Runtime Model

Applications should support the following modes where applicable:

• foreground run
• service install
• service uninstall
• service start
• service stop
• init (bootstrap + install + start)
• migration run
• backup
• restore
• health/doctor diagnostics

Runtime Requirements

• foreground mode and service mode should behave consistently
• graceful shutdown is required
• Docker deployment must be supported
• stdout logging should work well in containers
• rolling file logs should be supported for non-container deployments

---

5. Build, Versioning, and Artifact Standards

5.1 Versioning

All applications should use the version format:

yyyy.MM.dd.HHmm

Requirements:

• version must be generated centrally once per build
• the same version must be applied consistently across:
  • binaries
  • UI-visible version display
  • API/system version endpoints
  • release artifacts
  • Windows metadata where applicable

5.2 Embedded Resources

If /resources/icons exists and contains the expected Windows icon asset:

• the Windows build should embed the icon into the Windows binary
• the build should fail clearly if required icon resources are invalid or missing for Windows builds

When embed_ui_in_binary: yes (see Section 2.1):

• the built web UI must also be embedded into the backend binary via //go:embed and served by the backend as described in Section 3.4
• the build must fail clearly if the expected UI output directory is missing or empty, so a binary without a UI is never produced silently
• the build pipeline order must ensure the frontend is built before the backend

5.3 Binary Output Structure

Build automation should copy artifacts into:

/binaries
  /windows
    /amd64
    /arm64
  /macos
    /amd64
    /arm64
  /linux
    /amd64
    /arm64

Requirements:

• compile for Windows, macOS, Linux
• compile for amd64 and arm64 where supported
• copy outputs into predictable paths automatically
• naming should be deterministic

---

6. Standard Project Structure

/resources
  /icons
/binaries
  /windows
    /amd64
    /arm64
  /macos
    /amd64
    /arm64
  /linux
    /amd64
    /arm64
/backend
/frontend
/docs

6.1 Backend Suggested Structure

/backend
  /cmd
  /src or /internal
    /api
    /auth
    /config
    /crypto
    /db
      /migrations
      /repositories
    /logging
    /scheduler
    /services
    /system
    /types
    /validation

6.2 Frontend Suggested Structure

/frontend
  /src
    /app
    /components
    /features
    /hooks
    /lib
    /schemas
    /theme
    /types

---

7. Authentication and Authorization Framework

7.1 Browser Authentication

Default recommendation:

• Use NextAuth/Auth.js for interactive browser authentication and session management only

Supported approaches:

• OIDC via NextAuth/Auth.js
• local username/password via NextAuth Credentials provider, with credential verification handled by the backend

7.2 Backend Authority

The backend must remain the source of truth for:

• authorization
• RBAC / permissions
• API keys
• business-security decisions
• credential validation logic
• audit policy

NextAuth/Auth.js must not become the backend security boundary.

7.3 API Keys

API keys must be a separate authentication mechanism from user/browser authentication.

Requirements:

• may expire or never expire
• separately created, revoked, enabled, and audited
• shown only once at creation
• never retrievable again in plaintext
• displayed in a modal/dialog with copy-to-clipboard support
• stored using a secure verification strategy, not plaintext

7.4 CSRF and Session Security

• browser mutation flows must be CSRF protected
• secure cookie handling must be used where cookies are involved
• token/session policy must be centralized

7.5 Route Protection Pattern

The backend must protect administrative routes using a middleware-based gate from the very first HTTP commit. Retrofitting auth into an already-shipped route tree is a known source of rework and privilege-escalation bugs.

Requirements:

• The router must be organized around an explicit split between a public allowlist and an authenticated group. The framework default is that every route is authenticated; a route becomes public only by being added to the allowlist.
• The authenticated group must wrap every administrative resource (users, API keys, audit, settings, domain resources, export/import, etc.) with the standard auth middleware that validates the session/token and attaches the resolved principal to the request context.
• The public allowlist should contain only what must be reachable without credentials, typically: health, version, login, logout, CSRF bootstrap, and OIDC start/callback.
• Adding a new resource must not require remembering to attach middleware; resources added inside the authenticated group must inherit protection by construction.
• Integration tests must assert that each protected route returns 401 without a token and 200/2xx with a valid token, and that each public route works without a token. Both directions must be covered so the gate cannot silently regress.

7.6 First-Run Admin Bootstrap

On a fresh data directory, the application must be usable immediately without requiring the operator to hand-craft a row in the users table or a config file.

Requirements:

• On startup, after migrations complete, the backend must check whether any user exists. If the users table is empty, it must seed a single administrative user (conventionally named admin) with the highest-privilege role.
• The initial password source must follow this precedence:
  1. An environment variable (for example <APP>_BOOTSTRAP_PASSWORD) or its file companion (see Section 9.2) if present. A password supplied through this path is treated as an operator-provided credential and does not force a password change on first login.
  2. A fixed, well-known default credential (conventionally the same string as the username, e.g. admin/admin), paired with a password_reset_required flag on the seeded user so the first successful login is immediately forced through the password-change flow defined in the forced-password-change section below.
• When the default-credential path is taken, a clearly marked one-time banner must be printed to stdout and written to the structured log at warn level, stating the seeded username, the default password, and the requirement to change it on first login.
• The bootstrap must never downgrade or reset an existing administrator's password; it must be a no-op when any user already exists.

7.7 Forced Password Change

When a user's password_reset_required flag is set (from the default-password bootstrap path, an administrator-triggered reset, or any future reason), the application must force a password change before any other functionality becomes reachable.

Requirements:

• The users table must carry a password_reset_required boolean column. It must appear in the authenticated session/user payloads returned by /auth/login and /auth/me so the frontend can key its redirects off it.
• A dedicated authenticated endpoint (conventionally POST /auth/change-password) must accept the current and new passwords, verify the current one, enforce a minimum length, replace the hash, clear the flag, and emit an audit event for both success and failure.
• The frontend login handler must redirect to the password-change route whenever the login response carries passwordResetRequired: true. The authenticated route guard must bounce any other protected route back to the password-change route while the flag is set, so there is no way to reach product functionality until the default credential has been replaced.

7.8 Trusted Proxy Handling

When the application is deployed behind a reverse proxy or load balancer, X-Forwarded-* headers must be honored without making the service spoofable from arbitrary clients.

Requirements:

• Trust for forwarded headers must be opt-in and driven by a configurable list of CIDRs (for example <APP>_TRUSTED_PROXIES=10.0.0.0/8,127.0.0.1/32). The default must be empty, meaning no forwarded headers are trusted.
• A trusted-proxy middleware must run before authentication, authorization, and audit logging. When the immediate peer's address matches a trusted CIDR, the middleware must rewrite RemoteAddr from X-Forwarded-For (left-most untrusted hop) and the request scheme from X-Forwarded-Proto. When the peer is not trusted, all X-Forwarded-* headers must be ignored and the direct connection address must be used.
• Downstream handlers, audit events, rate limiters, and security decisions must use the middleware's rewritten values rather than re-reading the raw headers themselves.

---

8. Logging and Error Handling Framework

8.1 Standard Logging Format

• Standard logs: [TimestampUTC] - [Component] - [Level] - Message

• Error logs only: [TimestampUTC] - [Component] - [Level] - [File:Line:Column] - Message

8.2 Logging Style Requirements

• log messages must be plain and easy to understand
• messages should explain what is happening before, during, and after an operation when practical
• long-running tasks should emit progress-oriented messages at a reasonable cadence
• routine logs must not dump giant stack traces
• errors should be human-readable first
• component names must be consistent and centralized

8.3 Error Handling Requirements

• errors must be wrapped centrally
• error formatting must be centralized
• errors should capture source context automatically where possible
• file and line are required where practical for errors
• column should be included when available
• user-facing/API-facing errors must be understandable and safe
• low-level details should be reserved for debugging paths, not routine noise

---

9. Configuration Framework

9.1 Configuration Sources

Applications should support:

• environment variables
• secret files / mounted secrets
• optional configuration objects in the database if the product needs runtime-managed config

9.2 Environment Variable Naming and Secret Indirection

• Every configurable value must use a single, consistent environment variable prefix per application (for example <APP>_PORT, <APP>_DATA_PATH). The prefix must be chosen once and documented; individual features must not invent their own prefixes.
• Any variable that carries a secret or credential (encryption keys, bootstrap passwords, OIDC client secrets, signing keys, etc.) must also accept an indirect file-based form by convention: for each <APP>_FOO, the loader must also honor <APP>_FOO_FILE pointing at a path on disk whose contents are the value. This matches the Docker / Kubernetes / systemd secret-mounting idiom and avoids baking secrets into the process environment.
• Precedence must be: direct value wins over file-backed value if both are present, and an explicit empty string wins over a missing variable. The loader must trim trailing whitespace/newlines from file-backed values so a trailing newline in a mounted secret does not corrupt the value.
• Config loading must be centralized so this _FILE indirection is applied uniformly across all keys without per-call-site logic.

9.3 Config Export and Import

Applications that store runtime configuration in the database should support export/import.

Requirements:

• export format should be JSON initially
• exports should include schema/version metadata
• imports should support validation before apply
• imports should support dry-run preview
• secrets must never be exported in plaintext
• encrypted secrets may remain portable only when encryption keys match
• if keys do not match, imported secret-bearing records must be flagged for re-entry

---

10. Security and Secrets Framework

10.1 Key Material

Applications should support key/secret input via:

• environment variable
• mounted secret file

A 32-byte key minimum should be supported for encryption/signing where applicable.

10.2 Secrets Handling

• sensitive values must be encrypted at rest where needed
• secrets must never appear in plaintext in logs
• secrets must never be exposed back through normal APIs after creation
• sensitive fields must be redacted consistently

10.3 Password Handling

• use Argon2id for password hashing
• password verification and policy enforcement should be centralized

---

11. Database Standards

11.1 Global Data Rules

• UUIDv4 for all PK/FK by default
• UTC timestamps for all created/updated/deleted fields
• migrations required from day one
• WAL mode enabled for SQLite
• summary tables should be used where dashboards would otherwise rely on expensive queries

11.2 Backup and Restore

Applications using a local relational database should support:

• automatic backups
• manual backups
• restore with safety checks
• configurable retention count
• pre-restore safety backup

Default backup retention count:

• 3

---

12. API Standards

12.1 API Design Principles

• versioned API paths, e.g. /api/v1
• OpenAPI/Swagger support
• consistent error envelope
• pagination/filtering/sorting where appropriate
• server-side validation required
• resource-oriented route design preferred

12.2 CORS and Proxy Rules

• When embed_ui_in_binary: yes, the UI and API share one origin, so the framework default is an empty CORS allowlist (no cross-origin access). A cross-origin allowlist must only be configured when explicitly needed.
• When embed_ui_in_binary: no, production CORS origins must be explicitly configurable and localhost must be allowed for development.
• Trusted proxy handling must be implemented as middleware as described in Section 7.8. The default CIDR list must be empty (no proxy trust), and X-Forwarded-* headers must be ignored for any request whose immediate peer is not in that list.
• Downstream authn/authz decisions, audit events, and rate limiting must consume the middleware's normalized request values rather than re-reading raw forwarded headers.

12.3 Route Composition Pattern

• The router must physically separate a public route group from an authenticated route group, per Section 7.5. "Public" must be a short, reviewable allowlist; every other route must inherit the authenticated group.
• New feature handlers must be mounted inside the authenticated group unless the designer has made an explicit, reviewable decision to expose them publicly.
• The server must emit a startup log line enumerating the public routes so operators can audit the attack surface at boot.

---

13. UI / UX Standards

13.1 Design Direction

The UI should feel:

• polished
• premium
• modern
• spacious
• clear without being sparse
• dashboard-quality without clutter

Use:

• layered cards
• soft shadows
• rounded corners
• balanced whitespace
• strong visual hierarchy
• centralized design tokens for spacing, radii, typography, shadows, and color roles

13.2 Frontend Architecture Rules

• do not embed business logic in components
• keep forms schema-driven where practical
• centralize reusable layouts and primitives
• derive shared types from OpenAPI or a shared schema pipeline when practical
• integrate adopted templates cleanly so the UI feels native to the product

---

14. Cross-Cutting Maintainability Rules

1. No duplicated business logic across layers.
2. Centralize auth decisions.
3. Centralize logging helpers.
4. Centralize error wrapping and formatting.
5. Centralize timestamp generation in UTC.
6. Centralize UUID generation policy.
7. Centralize validation rules and enums.
8. Keep route handlers thin.
9. Keep frontend components presentation-focused.
10. Keep repositories organized and avoid scattered raw queries.
11. Make major architectural decisions once and document them.
12. Prefer reusable framework modules over per-app reinvention.

---

15. Standard Implementation Order

This order should be followed unless the app has a strong reason not to.

Phase 1 — Foundation

1. repository structure
2. config loading with env-or-file secret indirection (Section 9.2)
3. centralized logging
4. centralized error wrapping
5. secret/key loading
6. DB bootstrap
7. migrations
8. UUID/timestamp helpers
9. HTTP server skeleton with the public/authenticated route split (Section 7.5) and the trusted-proxy middleware (Section 7.8) wired in before any real handlers are mounted
10. health endpoint (on the public allowlist)
11. runtime/service abstraction
12. CLI commands
13. version generation
14. build scripts
15. binary output copying
16. Windows icon embedding if applicable

The router composition and proxy middleware belong in Phase 1, not Phase 2. Adding routes first and bolting on authentication later is an explicit anti-pattern: any resource added before the gate exists becomes an implicit public endpoint, and closing that gap after the fact requires auditing every mounted handler.

Phase 2 — Security and Auth

1. local auth model if needed
2. password hashing (Argon2id) and the login/logout/me handlers on the public allowlist
3. session/token issuance and validation middleware that feeds the authenticated group from Phase 1
4. first-run admin bootstrap from env/file, or a default credential paired with a forced password change on first login (Sections 7.6 and 7.7), wired into the run command after migrations
5. forced password-change endpoint and frontend route (Section 7.7) that runs before any other authenticated UI or API is reachable when the flag is set
6. NextAuth/Auth.js integration for browser login if UI exists
7. OIDC integration if needed
8. RBAC/authorization framework
9. API key framework
10. CSRF/session security
11. audit core, consuming the proxy middleware's normalized values

Phase 3 — Core Domain and CRUD

1. core tables/models
2. repositories/services
3. API endpoints
4. frontend CRUD/admin flows
5. summary tables where useful

Phase 4 — Background Work and Operational Features

1. scheduling/background jobs if needed
2. backup/restore
3. export/import
4. health/doctor tooling
5. history/audit views

Phase 5 — UX Polish and Hardening

1. dashboard composition
2. guided workflows
3. empty states
4. performance cleanup
5. documentation

---

16. MVP Acceptance Template

A generic application built on this framework is considered aligned when:

1. It runs in foreground and Docker.
2. Service lifecycle support exists where applicable.
3. Versioning follows yyyy.MM.dd.HHmm.
4. Build outputs land in /binaries/<os>/<arch>.
5. Logging follows the standard format.
6. Error logs include source context.
7. Config/env/secret loading is centralized, and every secret-bearing variable supports the _FILE companion form (Section 9.2).
8. DB migrations are in place from day one.
9. UUIDv4 and UTC timestamps are consistently used.
10. Local auth and/or OIDC are integrated correctly when required.
11. API keys remain separate from interactive auth.
12. CORS and trusted proxy handling are configured correctly, with the trusted-proxy middleware ignoring X-Forwarded-* from untrusted peers by default (Section 7.8).
13. Every administrative route is protected by the authenticated-group middleware (Section 7.5); the public route allowlist is short, reviewable, and logged at startup.
14. On a fresh data directory, the binary seeds a first administrative user via the bootstrap flow (Section 7.6) — either from <APP>_BOOTSTRAP_PASSWORD/_FILE when provided, or from the fixed default credential paired with password_reset_required so the first login is forced through the /change-password flow defined in Section 7.7.
15. The frontend bundle contains no hardcoded backend scheme/host/port and resolves the API base URL from the current origin at runtime (Section 3.2).
16. Backups and restore exist when local DB storage is used.
17. Config export/import exists when runtime DB config is used.
18. UI follows the shared design system direction.
19. Code is modular and avoids obvious duplication.
20. The UI delivery model matches the application's answer to the embed_ui_in_binary question (Section 2.1). For the framework default (yes), the released binary serves the full UI from its own HTTP server via //go:embed, with SPA fallback for deep links and no dependency on a separate web server, Node.js runtime, or static host.

---

17. Deviation Policy

If a future application deviates from this framework, the deviation should be explicit and documented.

Examples of acceptable reasons:

• the app is CLI-only and has no UI
• the app requires PostgreSQL from day one
• the app is Windows-only and uses native-only capabilities
• the app has no auth because it is a local-only utility

Deviations should be conscious, not accidental.

---

18. Final Positioning

This framework is the default blueprint for future applications.

It is intended to standardize:

• architecture
• security
• runtime behavior
• logging
• build outputs
• versioning
• data handling
• UI quality
• maintainability

So each new application can focus on domain value instead of repeatedly redesigning the same foundation.