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
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.
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.
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.
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.
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.
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.