Skip to content

Latest commit

 

History

History
178 lines (112 loc) · 4.09 KB

AGENTS.md

File metadata and controls

178 lines (112 loc) · 4.09 KB

NHS Wales Architecture Documentation Site

This repository contains the source for the GIG Cymru architecture documentation website. The following instructions are for an autonomous AI agent to work with this repository.

Quick Reference

View all available commands at any time:

just --list

The published documentation is available at: https://gigcymru.github.io/architecture/

Environment Setup

This project uses Just as a command runner (migrated from Make).

Prerequisites

  • Python 3.13 or higher
  • uv for package/env management
  • npm for markdown linting
  • Just for command running
  • Git

Initial Setup

Install the uv package manager if not already installed:

just install

Install the required Python packages and sync the environment:

just sync

Install Node.js dependencies for linting:

npm install

Quick Start (All-in-One)

Run the full setup and start the development server:

just

This will run: install → sync → build → run

Running Locally

Build the documentation site (output to ./site directory):

just build

Start the local development server (auto-reloads on file changes):

just run

The site will be available at http://127.0.0.1:8000/

Quality Assurance

Run all quality assurance checks (linting, spell checking, and link checking):

just qa

Important: Always run quality checks before committing to fix any issues.

Individual Quality Checks

Run markdown linting only:

just lint

Run spell checking only:

just spell

Note: In GitHub Actions PRs, spelling issues are displayed inline in the Files Changed view using the official streetsidesoftware/cspell-action GitHub Action.

Run internal link checking only:

just check-links

Run sync manifest verification only:

just verify-sync-manifest

All of these checks run automatically as part of just qa and in the GitHub PR workflow.

Documentation Structure

  • All documentation (in Markdown format) to be published on the site lives under the doc/ path.
  • Markdown documents should adhere to a 120 character line limit, unless it breaks URLs/links/special elements.
  • The documentation is built using Zensical, a modern static site generator.

Conventions

Architecture Decision Records (ADRs)

  • ADRs reside under the doc/decisions/ path.
  • ADRs should follow the agreed template: doc/design-authority/dhcw/architecture-decision-record-template.md
  • See doc/decisions/meta-decisions/architecture-decision-records-naming-conventions/index.md for naming conventions and rules.

Architecture Principles

  • Architecture Principles reside under the doc/principles/ path.

Diagrams

  • Mermaid is used to add diagrams to Markdown files.
  • See doc/decisions/meta-decisions/use-mermaid-for-documenting-diagrams/index.md for information.

PR Instructions

Before committing changes:

  1. Always run quality checks: just qa and fix any issues reported
  2. Always run build: just build and fix any WARNINGS raised
  3. Test the site locally: just run and verify your changes render correctly

Additional Commands

Document Conversion

Convert markdown templates to Word documents using Pandoc:

just word

This converts the ADR and design overview templates to .docx format.

Deployment

Build and deploy documentation to GitHub Pages (requires push permissions):

just deploy

The site will be deployed to: https://gigcymru.github.io/architecture/

Development Environment Options

This repository supports multiple development environments:

  1. GitHub Codespaces (Recommended) - Pre-configured cloud environment
  2. Local Development - Traditional local setup with uv and npm
  3. Container-based - Using Podman or Docker
  4. Just-based Workflow - Modern command runner (current approach)

See the README.md for detailed setup instructions for each option.