FlossWare Engineering Standards

This repository defines shared engineering standards, architecture decisions, and development conventions for the FlossWare ecosystem.

Core Principles

• Configuration is the source of truth.
• Defaults are minimal; capabilities are explicitly enabled.
• Components are modular and composable.
• Contracts define stable semantics; implementations realize those contracts without becoming the architectural authority.
• Repository names SHALL communicate contract, domain, and implementation-language roles where a contract family is split across repositories.
• Avoid unnecessary coupling.
• Favor automation, repeatability, and infrastructure-as-code.
• Released artifacts are derived, reproducible delivery outputs, not sources of truth.

See the core ADRs below for normative statements. AI-domain architecture decisions are maintained in FlossWare/loom-ai.

Architecture Decisions

Architecture decisions are documented as ADRs under adr/.

ADR	Topic
ADR-0001	Explicit Opt-In Cross-Cutting Behavior
ADR-0005	Event-Driven Internal Bus
ADR-0006	Cross-Cutting Decorators
ADR-0007	Unified Client-Service Contract
ADR-0008	Historical Free-First Platform Policy (Superseded)
ADR-0009	Core Architecture Principles
ADR-0010	REST Service Boundaries and Integration
ADR-0011	Stored Procedure Database Access Policy
ADR-0016	Configuration as Source of Truth
ADR-0022	Reproducible Build Artifacts and Distribution
ADR-0023	Canonical FlossWare AI Persistent State Root
ADR-0024	Contract-Centric Repository Layering and Naming
ADR-0025	AI Architecture Ownership

New ADRs SHOULD use adr/TEMPLATE.md.

AI-domain ADRs

AI architecture decisions are owned by FlossWare/loom-ai. This repository retains generic engineering principles and FlossWare-wide infrastructure decisions.

Reference architecture

• Reference architecture diagram (Mermaid)
• tftp-os client contract validation

ADR Process

All ADRs should include:

• Status
• Date
• Context
• Scope and Non-goals (recommended; required for new ADRs)
• Decision
• Consequences (positive and negative)
• Alternatives considered
• Related ADRs

RFC 2119 keywords are used consistently:

• SHALL / SHALL NOT: mandatory requirements (MUST is treated as equivalent to SHALL)
• SHOULD / SHOULD NOT: strong recommendation
• MAY: optional behavior