alunduil / alunduil/alunduil-infrastructure

Assess infrastructure organisation with C4 and decide on a DDD bounded-context restructure

Open
#255 0 comments 0 reactions 0 assignees View on GitHub
documentation enhancement
Dominant language
Shell
Stars
0
Forks
0
Avg merge
6h 42m
Merged PRs (30d)
97

Description

## Summary

An assessment of how this repo organises its infrastructure, ending in a
recorded decision on whether to restructure toward DDD bounded contexts for
better semantic alignment. C4 supplies the analysis frame; the ADR is the
deliverable.

## Motivation

The repo groups by tool and provider, not domain: top-level
`terraform/`, `github/`, `grafana/`, `scripts/`, `docs/`, and within
`terraform/alunduil/` a file per provider/resource type (`dns.tf`,
`storage.tf`, `grafana.tf`, `gcp_observability.tf`, `repositories.tf`,
...). Domains smear across these seams — observability spans
`terraform/alunduil/gcp_observability.tf`, `grafana.tf`, the `grafana/`
dashboards, and several how-tos; source-control governance spans
`repositories.tf`, `terraform/modules/github_repository/`, and `github/`
(Projects v2). As the repo grows, this technical grouping makes a single
domain change touch scattered files and obscures where a context begins
and ends. Worth assessing whether aligning along bounded contexts pays
off now or is premature.

## Scope

- Use the C4 levels as the **analysis frame**, not as a committed artifact —
#140 records C4/Structurizr as the rejected diagram tooling, and this issue
is the remaining C4 use in the repo:
- **Context** — external actors/systems this repo provisions or
integrates (GCP, Grafana Cloud, Cloudflare, GitHub, home infra,
UptimeRobot).
- **Container** — deployable/config units (bootstrap layer, alunduil
layer, Grafana dashboards, GitHub Projects applier, scripts).
- **Component** — logical groupings within each (DNS/edge,
state/bootstrap, observability, source-control governance, ...).
- Code-level detail only where it clarifies a boundary.
- Identify candidate DDD bounded contexts and where the current layout
cuts across them.
- Evaluate restructure options (domain-first directories vs. the current
provider-first `*.tf` split; whether `github/`, `grafana/`, `scripts/`
fold into per-context homes), with trade-offs — including the cost of
moving Terraform state addresses (`moved` blocks), and REUSE/CI churn.
- Weigh per-context credential scoping (#501) as an upside, sized against
the threat model (#85).
- Recommend: restructure now, defer, or keep — with the reasoning.

## Acceptance criteria

- [ ] Candidate bounded contexts and the seams the current layout crosses
are enumerated in the ADR's context section.
- [ ] A restructure recommendation (now / defer / keep) is recorded as an
ADR under `docs/adr/` with trade-offs, including state-move and CI cost.
- [ ] Any diagram is hand-authored Mermaid, inline in the ADR, per #140.

## Additional context

Spun out of the GCP-in-Grafana work (#88, #228, #252), where
observability landed spread across `terraform/alunduil/`, `grafana/`, and
`docs/how-to/`. C4 model: ; bounded contexts per
Evans/Vernon DDD. Current layout conventions live in `CLAUDE.md`.

Blocked by the threat model (#85): credential blast radius is the strongest
argument for splitting along context boundaries, and #85 is what sizes it.
Unblocks #501 (per-job provider credential scoping), which needs the
per-context root-module split this issue rules on.

Superseded scope: the original first acceptance criterion asked for a C4
model artifact in `docs/`. #84 closed as not planned on 2026-08-28 and #140
records hand-authored Mermaid as the diagram format with C4/Structurizr as
the rejected alternative, so C4 survives here as the frame for the analysis
only.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with CLAUDE.md, #85, and the listed Terraform, Grafana, GitHub, scripts, and docs paths; compare current provider-first seams with candidate bounded contexts using C4 as the analysis frame. Record the candidate contexts, trade-offs including moved blocks and CI/REUSE churn, and a now/defer/keep recommendation in a docs/adr/ ADR, with any diagram inline as Mermaid.

Written by the indexing model from the issue text.

Assessment

Tech stack
github, google-cloud, grafana, terraform
Domain
devops, documentation, infrastructure
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.