Embed badge
Show
Style
[](https://versuz.dev/skills/cilerler-melis-agent-skills-solution-structure)Free SKILL.md scraped from GitHub. Clone the repo or copy the file directly into your Claude Code skills directory.
npx versuz@latest install cilerler-melis-agent-skills-solution-structuregit clone https://github.com/cilerler/melis.gitcp melis/SKILL.MD ~/.claude/skills/cilerler-melis-agent-skills-solution-structure/SKILL.md---
name: solution-structure
type: guidance
applies_to:
- Developer
- Architect
- Documenter
- DBA
- Reviewer
mandatory: conditional
triggers:
- folder structure
- directory layout
- solution structure
- repo layout
- where does this go
- file placement
- opinionated folder
references: []
summary: Source of truth for the opinionated .NET solution folder structure (root scaffolding, /docs, /src/Modules/Component/Service hierarchy, /tools/Kubernetes, /tests) and the documentation placement rules that govern items inside it.
---
# Solution Structure
Source of truth for the opinionated **.NET solution** folder structure. When any skill places a file inside this repo, the rules come from here.
> Scope: this skill defines **only** the in-repo `.NET Solution` layout. It does **not** cover workspace structure (`%USERPROFILE%\Source\...`), company-wide document taxonomy, email aliases, RBAC / queue / artifact / test-project / repository naming — those are separate concerns owned elsewhere.
## Consumers
| Skill | Reads from this skill |
|-------|-----------------------|
| `dotnet-service-generator` | `/src/{Namespace}.Modules.{Module}/{Component}/{Service}/...` paths and per-service folder shape |
| `documentation-generator` | `/docs/...` placement, attachments convention, dated-vs-living filename rules, ticket/project folder shapes |
| `infrastructure` | `/tools/Kubernetes/{base,overlays}` Kustomize layout |
| `observability` | `/Observability/Grafana/` dashboard placement at app/module/component/service tiers |
| `mssql-table-scaffolder` | `/Resources/SQL/` placement when SQL is embedded in a service |
---
## Documentation Placement Rules
These rules govern items inside the `/docs/` and `Modules/.../Docs/` subtrees of the solution.
### Dated vs Living Filenames
| Doc type | Filename pattern | Rationale |
|----------|------------------|-----------|
| ADR | `{yyyyMMddHHmm}-{slug}.md` | Immutable once accepted |
| RFC | `{yyyyMMddHHmm}-{slug}.md` | Snapshot of a proposal at a point in time |
| Design Doc | `{yyyyMMddHHmm}-{slug}.md` | Snapshot of a design at a point in time |
| SOP | `{yyyyMMddHHmm}-{slug}.md` | Versioned procedure |
| PIR (Postmortem) | `{yyyyMMddHHmm}-{slug}.md` | Tied to an incident date |
| Test Plan (release/app-level) | `{yyyyMMddHHmm}-{slug}.md` | Release/initiative scoped |
| Project Status Update | `{yyyyMMddHHmm}-{slug}.md` | Iterative, dated |
| Architecture Overview | `{slug}.md` | Living — updated as system evolves |
| Runbook | `{slug}.md` | Living — updated as system evolves |
| Test Cases | `{slug}.md` | Living — updated as features change |
| Singletons (`README`, glossaries, dictionaries, tech stack) | fixed name | One per repo |
### Attachments Convention
Per-document supporting files (diagrams, screenshots, spreadsheets, raw data, recordings) live in a sibling `attachments/{basename}/` folder, where `{basename}` is the document filename **without** `.md`.
Exceptions:
- **Singletons** at `/docs/` root (`business-glossary.md`, `data-dictionary.md`, `tech-stack-overview.md`) — no `attachments/`. Promote to a typed folder if support material is needed.
- **Non-markdown reference folders** (`/specs`, `/diagrams`, `/notebooks`) — no `attachments/`; those files *are* the artifacts.
### Tickets and Projects
- One folder per ticket: `/docs/tickets/GITHUB-{N}/` with required `Handoff.md` + `attachments/Handoff/`.
- One folder per project: `/docs/projects/P{N}/` with required `BusinessCase.md`, optional `BusinessCaseFinancialModel.md`, `Retrospective.md`, `TestPlan.md`, `StatusUpdates/{yyyyMMddHHmm}-{slug}.md`, `attachments/{BasenameMatchingDoc}/`.
### Doc Identifier Schemes
- **Tickets** use the external tracker identifier, e.g. `GITHUB-{N}` for GitHub issues.
- **Projects** use a sequential internal ID: `P1`, `P2`, `P3`, ...
- **Documents** use a timestamp-slug ID: `{ABBR}-{yyyyMMddHHmm}-{slug}` where `ABBR` is the doc-type abbreviation (`ADR`, `RFC`, `PIR`, ...). Filename omits the abbreviation prefix (folder context supplies it). In-doc references use the full form.
---
## .NET Solution Folder Structure
> **Attachments convention (`/docs/` only):** per-document supporting files (diagrams, screenshots, spreadsheets, raw data, recordings) live in a sibling `/attachments/{basename}/` folder, where `{basename}` is the document filename **without** `.md`. Exceptions are flagged inline in the tree:
> - **Singletons** at `/docs/` root (`business-glossary.md`, `data-dictionary.md`, `tech-stack-overview.md`) — no `/attachments/`.
> - **Non-markdown reference folders** (`/specs`, `/diagrams`, `/notebooks`) — no `/attachments/`; those files *are* the artifacts.
```
/.vscode // Visual Studio Code settings
- settings.json // Workspace settings
- launch.json // Debugging configuration
- tasks.json // Task configuration
- extensions.json // Recommended extensions
/.git // Git configuration
- config // Git configuration file
/.github // GitHub configuration
- CODEOWNERS // Code owners for the repository
- PULL_REQUEST_TEMPLATE.md // Pull request template
/ISSUE_TEMPLATE // Issue templates
- bug_report.yml // Bug report template
- feature_request.yml // Feature request template
- custom_template.yml // Custom template
/workflows // GitHub Actions workflows
- ci.yml // CI/CD pipeline for continuous integration
- checks.yml // CI/CD pipeline for running checks and tests
/docs // App-level documentation
- README.md // Master index — pointers to sections below
- business-glossary.md // SINGLETON — no /attachments/ (promote to its own typed folder if support material is needed)
- data-dictionary.md // SINGLETON — no /attachments/
- tech-stack-overview.md // SINGLETON — no /attachments/
/adrs // Architecture Decision Records — why we chose X over Y (immutable once accepted)
- {yyyyMMddHHmm}-{slug}.md // One decision per file (e.g. 202504141430-use-event-sourcing.md)
/attachments
/{yyyyMMddHHmm}-{slug} // Per-doc supporting files (diagrams, screenshots, data, recordings)
/rfcs // Request for Comments — proposals under discussion, may or may not be accepted
- {yyyyMMddHHmm}-{slug}.md
/attachments
/{yyyyMMddHHmm}-{slug}
/designs // Technical Design Documents — narrative explanation of how a feature/system works
- {yyyyMMddHHmm}-{slug}.md
/attachments
/{yyyyMMddHHmm}-{slug}
/specs // Machine-readable contract definitions — OpenAPI, GraphQL, JSON Schema, etc. (no /attachments/ — these ARE the artifacts)
- {slug}.yaml
- {slug}.json
/diagrams // Shared system/architecture diagrams referenced by multiple docs (no /attachments/ — these ARE the artifacts)
- {slug}.puml // PlantUML source
- {slug}.excalidraw // Excalidraw source
- {slug}.mermaid // Mermaid source
/notebooks // Jupyter notebooks for analysis or runnable examples (no /attachments/ — these ARE the artifacts)
- {slug}.ipynb
/architectures // Architecture overviews — Diátaxis "Explanation" docs describing how existing systems / modules / components / areas work
- {slug}.md // Living documents — no date prefix. Multiple per scope (e.g., system.md, auth-flow.md, billing-pricing-engine.md)
/attachments
/{slug}
/runbooks // App-wide operational procedures (deploy, backup, restore, etc.)
- {slug}.md // Living documents — no date prefix (updated as systems evolve)
/attachments
/{slug}
/sops // Standard Operating Procedures — formalized org processes
- {yyyyMMddHHmm}-{slug}.md
/attachments
/{yyyyMMddHHmm}-{slug}
/pirs // Post Incident Reviews — what broke, why, how we fixed it
- {yyyyMMddHHmm}-{slug}.md
/attachments
/{yyyyMMddHHmm}-{slug}
/test-plans // App / release-level test strategy (opt-in; required in regulated contexts)
- {yyyyMMddHHmm}-{slug}.md // Use when scope is a release or initiative not tied to a P{N} project
/attachments
/{yyyyMMddHHmm}-{slug}
/test-cases // QA verification of acceptance criteria
- {slug}.md // Living documents — no date prefix (updated as features change)
/attachments
/{slug}
/tickets // Per-ticket working artifacts and handoffs
/GITHUB-{N} // Always a folder; one per ticket (identifier from external tracker, e.g. GITHUB-{N})
- Handoff.md // REQUIRED — final handoff summary at ticket resolution
/attachments
/Handoff // Subfolder name matches doc basename — holds scripts, screenshots, investigation notes, raw data, recordings
/projects // Per-project working artifacts and documentation
/P{N} // Always a folder; one per project (sequential internal ID: P1, P2, P3, ...)
- BusinessCase.md // REQUIRED — initiates the project (scope, rationale, approval)
- BusinessCaseFinancialModel.md // Optional — financial evaluation (OPEX/CAPEX, ROI, payback period)
- Retrospective.md // End-of-project retrospective
- TestPlan.md // Optional — project-scoped test strategy (sits alongside BusinessCase)
/StatusUpdates // Iterative status reports over the life of the project
- {yyyyMMddHHmm}-{slug}.md
/attachments
/{yyyyMMddHHmm}-{slug} // Per-update supporting files
/attachments
/BusinessCase // Each subfolder matches a doc basename in this folder
/BusinessCaseFinancialModel
/Retrospective
/TestPlan
/tools
/Kubernetes
- kustomization.yaml // Kustomize configuration for Kubernetes
/base
- kustomization.yaml // Base kustomize configuration for Kubernetes
- deployment.yaml // Base deployment configuration for Kubernetes
- service.yaml // Base service configuration for Kubernetes
/overlays
/integration
/base // Base configuration for Integration environment
- kustomization.yaml // Base kustomize configuration for Integration environment
- deployment.yaml // Base deployment configuration for Integration environment
- service.yaml // Base service configuration for Integration environment
/default // Default configuration for Integration environment
- kustomization.yaml // Default kustomize configuration for Integration environment
- deployment.yaml // Default deployment configuration for Integration environment
- service.yaml // Default service configuration for Integration environment
/alternative // Alternative configuration for Integration environment
- kustomization.yaml // Alternative kustomize configuration for Integration environment
- deployment.yaml // Alternative deployment configuration for Integration environment
- service.yaml // Alternative service configuration for Integration environment
/testing
/base
- kustomization.yaml
- deployment.yaml
- service.yaml
/default
- kustomization.yaml
- deployment.yaml
- service.yaml
/alternative
- kustomization.yaml
- deployment.yaml
- service.yaml
/staging
/base
- ...
/default
- ...
/alternative
- ...
/production
/...
/tests
- App.http // Cross-module HTTP request tests
- {ModuleName}.http // Cross-component tests within a module
- {ComponentName}.http // Cross-service tests within a component
- {ServiceName}.http // Tests for one service's API endpoints
/Company.Project.Domain.Integration.Tests
- Company.Project.Domain.Integration.Tests.csproj
- EnterpriseServiceTests.cs
/Company.Project.Domain.Unit.Tests
- Company.Project.Domain.Unit.Tests.csproj
- EnterpriseServiceTests.cs
/Company.Project.Host.E2E.Tests
- Company.Project.Host.E2E.Tests.csproj
- HealthCheckTests.cs
/Company.Project.Host.Integration.Tests
- Company.Project.Host.Integration.Tests.csproj
- HealthCheckTests.cs
/Company.Project.Host.Unit.Tests
- Company.Project.Host.Unit.Tests.csproj
- HealthCheckTests.cs
/Company.Project.Tests.Common // Shared test utilities, fixtures, mocks
- Company.Project.Tests.Common.csproj
/...
.dockerignore // Docker ignore file
.editorconfig // Editor configuration file
.gitattributes // Git attributes file
.gitignore // Git ignore file
LICENSE // License file
README.md // Readme file explains the project
CHANGELOG.md // Changelog file for the project
azure-pipelines.yml // Azure DevOps pipeline configuration
Company.Solution.sln // Visual Studio solution file
/src
/Company.Project.Abstractions
/Company.Project.Extensions
/Company.Project.Domain
/Company.Project.Host
- Program.cs // Entry point for the application
- ProgramExtensions.cs // Extension methods for the program
- StartupBackgroundService.cs // Initial background service for the application
- StartupHealthCheck.cs // Health check for the application
- AppConfigurationExtensions.cs // Configuration extensions for the application
- appsettings.json // Configuration settings for the application
- appsettings.Development.json // Configuration settings for the development environment
- appsettings.Integration.json // Configuration settings for the integration environment
- appsettings.Testing.json // Configuration settings for the testing environment
- appsettings.Staging.json // Configuration settings for the staging environment
- appsettings.Production.json // Configuration settings for the production environment
- Dockerfile // Docker configuration for containerization
- Company.Project.Host.csproj // Project file
- Directory.Build.props // Common properties for all projects in the solution
- Buildinfo.txt // Build information to show when the app starts
- App.razor // Main application component
- Routes.razor // Route configuration for the application
/Properties
- launchSettings.json // Debugging settings for the project, Visual Studio and .NET Core CLI
/Resources
/SQL
- Constants.cs
- Query1.sql
- Query2.sql
- ...
/...
/wwwroot
- index.html // Default HTML file for the application
- favicon.ico // Favicon for the application
- ...
/css
- app.css
- ...
/Pages
- Page1.razor // Razor page for the application
- Page2.razor
- ...
/PageComponents
- PageComponent1.razor // Page component for the application
- PageComponent2.razor
- ...
/Layout
- MainLayout.razor // Main layout component
- NavMenu.razor // Navigation menu component
- _Imports.razor // Import statements for the application
/Abstractions // App-wide shared contracts (cross-module)
/Events
/Interfaces
/Models // Enums, value objects, shared DTOs
/Requests
/Responses
/Contracts // App-wide internal interfaces for shared helpers
/Exceptions // App-wide base exceptions
/Extensions
- StartupExtensions.cs // Registers modules — feature flags decide which are active per deployment
/Internals // App-wide shared helper implementations
/Observability
/Grafana // Platform overview dashboard
- dashboard.json
/Company.Project.Modules.{Module1}.Abstractions // Separate csproj — module's public contract (cross-module)
- Company.Project.Modules.{Module1}.Abstractions.csproj
/Events
/Interfaces
/Models // Enums, value objects, shared DTOs
/Requests
/Responses
/Company.Project.Modules.{Module1} // Module project — owns components and services as folders
- Company.Project.Modules.{Module1}.csproj // References its .Abstractions sibling; references other modules' .Abstractions when consuming their contracts
- Constants.cs // Module-wide constants
/Contracts // Module-wide internal interfaces for shared helpers
/Docs // Module-scoped documentation (optional)
/adrs // Module-specific architectural decisions
/rfcs // Module-specific proposals
/runbooks // Module-level operational procedures
/Exceptions // Module-level base exceptions
/Extensions
- StartupExtensions.cs // Registers all components in this module
/Internals // Module-wide shared helper implementations
/Observability
/Grafana // Module-level domain health dashboard
- dashboard.json
/{Component1} // Folder inside module project — always required (even single-component modules)
/Abstractions // Component's public contract (cross-component within module — folder, NOT separate csproj)
/Events
/Interfaces
/Models
/Requests
/Responses
/Contracts // Component-wide internal interfaces for shared helpers
/Docs // Component-scoped documentation (optional)
/adrs // Component-specific architectural decisions
/rfcs // Component-specific proposals
/runbooks // Component-level operational procedures
/Exceptions // Component-level base exceptions
/Extensions
- StartupExtensions.cs // Registers all services in this component
/Internals // Component-wide shared helper implementations
/Observability
/Grafana // Component-level aggregated dashboard
- dashboard.json
- Constants.cs // Component-wide constants
/{Service1} // Folder — full service structure
/Abstractions // Public contract (cross-service within component — folder)
/Events // Domain events
/Interfaces // Public interfaces (when externally consumed)
/Models // Enums, value objects, shared DTOs
/Requests // Request DTOs
/Responses // Response DTOs
/Api // HTTP endpoints (optional)
- {ServiceName}Api.cs // Route group definition
- {Verb}Endpoint.cs // One file per endpoint
/Clients // External HTTP API wrappers
/Configuration // Settings and config binding
- {ServiceName}Settings.cs
/Contracts // Internal interfaces (DI/testing)
- I{ServiceName}.cs // Default: internal
/Docs // Service-scoped documentation (optional)
- README.md // Service overview
- runbook.md // Service-specific operational procedures
- test-plan.md // Service-specific test strategy
/Exceptions // Service-specific exceptions
/Extensions // DI registration, model extensions
- StartupExtensions.cs
/Internals // Internal helper implementations
/Mappers // Object mapping between types
/Models // Internal entities/domain objects
/Observability // Dashboards and diagnostics
/Grafana // Per-service dashboard
- dashboard.json
/Resources // Embedded resource files — optional (SQL, templates, etc.)
/SQL
- {Name}.sql
- ResourceLoader.cs // Lazy loader for embedded resources
- Constants.cs // Resource file name constants
/Validators // Custom validation attributes
- Constants.cs // Service constants + Metrics nested class
- {ServiceName}Service.cs // Core business logic
- {ServiceName}Worker.cs // Background service lifecycle (optional)
- {ServiceName}HealthCheck.cs // Health monitoring (optional)
/{Service2}
/...
/{Component2}
/...
/Company.Project.Modules.{Module2}.Abstractions
/...
/Company.Project.Modules.{Module2}
/...
```