Skip to main content

Architecture Documentation

This site contains the authoritative enterprise and technology architecture.

It is structured to make architectural intent, constraints, and realization explicit and traceable over time.

This is not a collection of diagrams or static artifacts. It is a living architectural blueprint.

How the Architecture Is Organized​

The architecture is organized outside-in:

  1. Outer constraints
    Forces that bound and shape all architectural decisions
    (strategy, regulatory, market, and technology constraints)

  2. Architectural aspects
    Orthogonal lenses used to reason about the system:

    • principles and patterns
    • components
    • capabilities

  3. Technology architectures
    Concrete, bounded system realizations that implement enterprise intent

If a question about why, what, or how cannot be answered by navigating this structure, the architecture is incomplete.

Documentation Areas​

  • Enterprise Architecture
    Defines enterprise intent, constraints, and shared architectural structure.

  • Technology Architectures
    System-level blueprints for specific technologies, examined using the same architectural logic as the enterprise.

  • Appendix
    Supporting reference material that is useful but not part of core architectural reasoning.

How to Use This Documentation​

  1. Start with outer constraints to understand intent and boundaries.
  2. Review principles and patterns to understand architectural guidance.
  3. Examine components to understand structure.
  4. Use capabilities to understand behavior.
  5. Dive into technology architectures only after enterprise context is clear.

Architectural Discipline​

Architecture here is defined by:

  • clarity of intent
  • consistency of abstraction
  • traceability of decisions

When the structure no longer makes sense, the architecture has drifted.

Documentation Directory Structure​

This README lives at the root of /docs and describes the organization of the authoritative architecture documentation below.

docs/
├── README.md                     – Architectural orientation and reading guide
├── enterprise-architecture/      – Enterprise-level architectural intent
│   ├── README.md                 – Enterprise architecture overview
│   ├── ASSUMPTIONS.md            – Explicit architectural assumptions
│   ├── RISKS.md                  – Known risks and unresolved concerns
│   ├── 00_outer-constraints/     – Strategy, regulatory, and market constraints
│   │   ├── README.md             – Constraint framing
│   │   ├── business-and-it-strategy.md
│   │   └── business-and-technology-trends.md
│   ├── 01_aspects/               – Orthogonal architectural lenses
│   │   ├── README.md             – Aspect-level guidance
│   │   ├── capabilities/         – Business and technical capabilities
│   │   ├── components/           – Logical and physical system structure
│   │   └── principles-and-patterns/ – Enterprise-wide principles and mandated patterns
├── appendix/                     – Supporting and governance material
│   └── steering-committee/       – Steering committee context and artifacts

Technology Architectures​

Concrete system realizations live under the components hierarchy and follow the same architectural discipline as the enterprise model.

enterprise-architecture/01_aspects/components/technology/
├── iot-ingest-modernization/     – Device-to-cloud ingestion boundary
├── legacy-estate/                – Characterization & decommission of pre-platform systems
├── next-gen-cloud-platform/      – Target cloud and data platform
├── portal/                       – Clinical administration surface (operating)
├── sleepwatch/                   – The shipping clinical device
├── sleepwatch-mobile/            – Companion app / BLE relay (development stage)
└── sleepwatch-next/              – Next hardware revision (assessment stage)

Each technology architecture is internally structured as:

<technology-domain>/
├── README.md                     – Domain scope and intent
├── 00_outer-constraints/         – Functional and non-functional requirements
├── 01_aspects/
│   ├── capabilities/             – Exactly three views: development, operational, runtime-execution
│   ├── components/               – Exactly four views: application, data, infrastructure, platform
│   └── principles-and-patterns/  – Domain-specific guidance

This structure is intentional. If documentation cannot be placed cleanly within it, the architectural reasoning is incomplete.

Structural Grammar (hard rules)​

  1. Numbering is semantic, and constraints are rings. 00_outer-constraints are agreed first and bind everything nested beneath them, at every depth — they bound all thought within them. Binding is transitive: inner 00_outer-constraints may tighten an outer ring, never loosen or contradict it. Constraints are imposed on a node from outside it; a node never negotiates its own constraints, and deviations are justified at the level that owns the ring (see Enterprise Outer Constraints).
  2. The structure is recursive. A technology architecture is examined with the same logic as the enterprise: constraints, then aspects (principles-and-patterns / capabilities / components).
  3. Aspect vocabularies are fixed. Technology-level capabilities are exactly development, operational, runtime-execution; technology-level components are exactly application, data, infrastructure, platform. Do not add siblings — deepen within a view instead (e.g. runtime-execution/actigraphy-measurement/).
  4. Supporting graphics are allowed as nested items (e.g. context-map/, .mmd diagrams). They illustrate decisions; they never replace them.
  5. Every directory README defines the exercise needed and the template to fill in. The artifacts beside it are the filled-in result. A directory without a README is structurally incomplete.
  6. New catalog entries are admitted under 01_aspects/components/technology/ only, and only with the full shape above in place from the first commit.