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.

---

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

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

---

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

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

---

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 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

• localhost should be allowed by default for development
• production CORS origins must be configurable
• trusted proxy handling must be configurable
• forwarded headers should only be trusted from configured proxies
• auth/security decisions must correctly account for proxy-forwarded scheme/host/IP when trust is enabled

---

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
3. centralized logging
4. centralized error wrapping
5. secret/key loading
6. DB bootstrap
7. migrations
8. UUID/timestamp helpers
9. health endpoint
10. runtime/service abstraction
11. CLI commands
12. version generation
13. build scripts
14. binary output copying
15. Windows icon embedding if applicable

Phase 2 — Security and Auth

1. local auth model if needed
2. NextAuth/Auth.js integration for browser login if UI exists
3. OIDC integration if needed
4. RBAC/authorization framework
5. API key framework
6. CSRF/session security
7. audit core

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.
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.
13. Backups and restore exist when local DB storage is used.
14. Config export/import exists when runtime DB config is used.
15. UI follows the shared design system direction.
16. Code is modular and avoids obvious duplication.

---

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.