From c6a17a1fecad21e7c96e8964481043ba7879e95d Mon Sep 17 00:00:00 2001 From: Billy Box Date: Fri, 22 May 2026 00:17:57 -0700 Subject: [PATCH 1/7] Document modular template architecture --- README.md | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index ab4ed57..211ed2e 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ This template is intentionally generic so it can be adopted across teams, produc - **Faster onboarding**: contributors and maintainers get clear guidance. - **Scalable governance**: reusable conventions for labels, milestones, and releases. - **Production-grade defaults**: practical configuration for common Git and editor workflows. +- **Modular architecture**: separate core logic, integrations, extensions, config, scripts, and tests. ## Included components @@ -28,6 +29,14 @@ This template is intentionally generic so it can be adopted across teams, produc - `CODEOWNERS` - Standards and governance documentation: - `docs/REPOSITORY_STANDARDS.md` + - `docs/ARCHITECTURE.md` +- Modular template structure: + - `core/` + - `providers/` + - `plugins/` + - `config/` + - `scripts/` + - `tests/` - Baseline repository config: - `.editorconfig` - `.gitattributes` @@ -61,10 +70,15 @@ Use [Semantic Versioning](https://semver.org/) and keep a human-readable `CHANGE See `docs/REPOSITORY_STANDARDS.md` for reusable naming and governance conventions. +## Architecture conventions + +See `docs/ARCHITECTURE.md` for the reusable modular layout, including core/provider/plugin/config/test separation. + ## Suggested next steps - Review prebuilt GitHub Actions workflows in `.github/workflows/` and enable commands for your stack. - Add language/tool-specific linting, formatting, and tests as your project grows. +- Fill in the modular folders with project-specific implementation code. - Add project-specific architecture and operations documentation in `docs/`. - Configure `release.yml` for semantic release PRs/tags if you publish artifacts. @@ -76,13 +90,18 @@ See `docs/REPOSITORY_STANDARDS.md` for reusable naming and governance convention workflows/ PULL_REQUEST_TEMPLATE.md CODEOWNERS +core/ +providers/ +plugins/ +config/ +docs/ +scripts/ +tests/ CHANGELOG.md CODE_OF_CONDUCT.md CONTRIBUTING.md LICENSE SECURITY.md -docs/ -scripts/ ``` ## Automation included From 9e605d905108ad233e41f810cc3f1f95feaeb7d8 Mon Sep 17 00:00:00 2001 From: Billy Box Date: Fri, 22 May 2026 00:18:16 -0700 Subject: [PATCH 2/7] Add modular architecture conventions --- docs/ARCHITECTURE.md | 129 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 docs/ARCHITECTURE.md diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..e161efe --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,129 @@ +# Architecture + +This repository is a reusable template, so the architecture intentionally defines conventions without assuming a specific runtime, framework, product, or deployment target. + +Use these folders as stable seams for future projects. Keep implementation code small, composable, and easy to replace. + +## Layout + +```text +core/ +providers/ +plugins/ +config/ +scripts/ +tests/ +docs/ +``` + +## Folder responsibilities + +### `core/` + +Contains framework-independent domain logic. Code in `core/` should avoid direct network, file-system, database, UI, or vendor-specific calls when possible. + +Good candidates: + +- domain models +- pure transformations +- validation rules +- orchestration interfaces +- reusable service boundaries + +### `providers/` + +Contains adapters for external systems or runtime-specific integrations. + +Good candidates: + +- API clients +- database adapters +- file-system adapters +- cloud service adapters +- AI/model provider adapters + +Providers should depend on `core/` contracts instead of forcing `core/` to know vendor details. + +### `plugins/` + +Contains optional extensions that can be added, removed, or replaced without rewriting core behavior. + +Good candidates: + +- feature modules +- command extensions +- workflow extensions +- experimental integrations + +A plugin should declare what it needs and expose a small entry point. Avoid hidden global state. + +### `config/` + +Contains configuration defaults, schemas, examples, and environment documentation. + +Good candidates: + +- example config files +- schema files +- environment variable documentation +- validation helpers + +Do not commit secrets. Prefer explicit placeholders such as `EXAMPLE_TOKEN` or `YOUR_API_KEY_HERE`. + +### `scripts/` + +Contains local development, maintenance, and automation helpers. + +Scripts should be safe to run repeatedly, explain what they are doing, and avoid destructive behavior unless explicitly documented. + +### `tests/` + +Contains automated tests and fixtures. + +Suggested organization: + +- `tests/unit/` for isolated logic tests +- `tests/integration/` for adapter or provider tests +- `tests/fixtures/` for reusable sample data + +## Dependency direction + +Keep dependencies flowing inward: + +```text +plugins -> providers -> core +scripts -> project tooling +config -> runtime setup +``` + +`core/` should not import from `providers/` or `plugins/`. This keeps the template portable and makes future rewrites less painful. + +## Extension pattern + +When adding a new capability: + +1. Define the stable behavior in `core/`. +2. Put external-service details in `providers/`. +3. Put optional feature wiring in `plugins/`. +4. Document configuration in `config/`. +5. Add tests under `tests/`. + +## Configuration pattern + +Prefer configuration that is: + +- explicit +- documented +- environment-aware +- safe by default +- easy to override in CI + +Template repositories should use example files instead of real secrets or machine-specific paths. + +## Portability rules + +- Avoid hardcoded absolute paths. +- Keep OS-specific commands isolated in scripts. +- Prefer plain text docs and simple shell helpers. +- Keep provider-specific behavior outside `core/`. +- Make optional features removable without breaking the baseline template. From ff31e5f0fc7fa3bdcd5572bca28fde56563b7fd9 Mon Sep 17 00:00:00 2001 From: Billy Box Date: Fri, 22 May 2026 00:18:30 -0700 Subject: [PATCH 3/7] Add core folder marker --- core/README.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 core/README.md diff --git a/core/README.md b/core/README.md new file mode 100644 index 0000000..22425a9 --- /dev/null +++ b/core/README.md @@ -0,0 +1,3 @@ +# Core + +Framework-independent project logic belongs here. From ecf24ea17cc8b5ce104e52f48bdc05b2bf44c27f Mon Sep 17 00:00:00 2001 From: Billy Box Date: Fri, 22 May 2026 00:18:40 -0700 Subject: [PATCH 4/7] Add providers folder marker --- providers/README.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 providers/README.md diff --git a/providers/README.md b/providers/README.md new file mode 100644 index 0000000..4b2542b --- /dev/null +++ b/providers/README.md @@ -0,0 +1,3 @@ +# Providers + +External service adapters and runtime integrations belong here. From 3305b76700950ac7df3edeeebde13b03a0a507dc Mon Sep 17 00:00:00 2001 From: Billy Box Date: Fri, 22 May 2026 00:18:54 -0700 Subject: [PATCH 5/7] Add plugins folder marker --- plugins/README.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 plugins/README.md diff --git a/plugins/README.md b/plugins/README.md new file mode 100644 index 0000000..23dd5bc --- /dev/null +++ b/plugins/README.md @@ -0,0 +1,3 @@ +# Plugins + +Optional extensions and feature modules belong here. From 01a3adf351f4ac2ffe2d418f48265ea8bdc12ec4 Mon Sep 17 00:00:00 2001 From: Billy Box Date: Fri, 22 May 2026 00:19:03 -0700 Subject: [PATCH 6/7] Add config folder marker --- config/README.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 config/README.md diff --git a/config/README.md b/config/README.md new file mode 100644 index 0000000..5600011 --- /dev/null +++ b/config/README.md @@ -0,0 +1,3 @@ +# Config + +Configuration examples, schemas, and environment notes belong here. From f48270e0acd2611ce48f9c5208fdad5a9eef6885 Mon Sep 17 00:00:00 2001 From: Billy Box Date: Fri, 22 May 2026 00:19:13 -0700 Subject: [PATCH 7/7] Add tests folder marker --- tests/README.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 tests/README.md diff --git a/tests/README.md b/tests/README.md new file mode 100644 index 0000000..cc7914e --- /dev/null +++ b/tests/README.md @@ -0,0 +1,3 @@ +# Tests + +Automated tests, fixtures, and validation examples belong here.