Project structure · Backend
ASP.NET Core Web API project structure
Opens with creditsA REST API in C# on .NET 10 with minimal API endpoints grouped by feature, EF Core and PostgreSQL, JWT auth with policies, xUnit and Testcontainers tests, and everything production needs: health checks, OpenTelemetry, rate limits, versioning, caching and a CI pipeline. It shows the popular clean architecture split (Api, Application, Domain, Infrastructure) honestly, and at Expert grows into Aspire, a modular monolith and enforced boundaries.
Curated by Tauseef FayyazIntermediate218 files and folders.NET 10 (LTS), ASP.NET Core 10, EF Core 10Checked October 2026How it grows
Each stage opens the explorer there
- 1Day 1What the scaffold and your first hour give you16 files and folders
- 2GrowingWhat a real app with features and tests adds+94 files and folders
- ProductionWhat running it for real users adds+44 files and foldersOpens with credits
- ExpertWhat a team needs to keep it healthy for years+64 files and foldersOpens with credits
How it is organised
- One solution, with production code in src/ and tests in tests/. The .slnx file is how the IDE, `dotnet build` and CI see the whole project, and Directory.Build.props, Directory.Packages.props and global.json keep every project on the same settings, package versions and SDK.
- Keep Program.cs a short list of registrations and endpoint mappings. Each feature maps its own endpoints from its own file as a route group, and each concern (auth, rate limiting, observability) registers itself from an extension method.
- Clean architecture (Api, Application, Domain, Infrastructure) keeps the business rules free of web and database code. It pays off in large, long-lived codebases with several teams; for a small API it is ceremony, and one Api project with a folder per feature is the better start. Inside every layer, group by feature (Orders, Products), never by file type.
- Dependencies point inwards: Api references Application and Infrastructure, Infrastructure references Application, Application references Domain, and Domain references nothing. At Expert an architecture test fails the build when someone breaks that rule.
- Secure by default: a fallback authorization policy requires a signed-in user on every endpoint, so a forgotten attribute means 401, not an open endpoint. Anonymous routes opt out on purpose.
- The database schema is owned by EF Core migrations that are committed, reviewed and applied by the pipeline as a separate step, never created on the fly in production.
- Configuration layers from appsettings.json to appsettings.{Environment}.json to user-secrets to environment variables, bound to options classes that are validated at startup. Secrets live in user-secrets locally and in Key Vault in production.
- Errors leave the API as RFC 9457 problem details from IExceptionHandler classes, never as stack traces, and every response carries a trace id that links it to the logs.
- Tests grow with the app: fast xUnit unit tests for the rules, WebApplicationFactory integration tests against a real PostgreSQL in Testcontainers, then architecture, contract, load and mutation tests once the codebase and team are big enough to need them.
At the top of the project
Open one in the explorer for the full story
- Shop/
- .config/Local .NET tool manifest, so everyone uses the same dotnet-ef version.1 inside
- .git/Git history for the whole solution.
- .vscode/Shared VS Code settings for teammates who do not use Visual Studio or Rider.2 inside
- src/Every project that ships: the API, its class libraries and, at Expert, Aspire and modules.4 inside
- tests/Test projects, kept apart from production code, one project per kind of test.2 inside
- .editorconfigCode style and analyzer severities every editor, dotnet format and the build follow.
- .env.exampleThe variables compose.yaml expects, with safe placeholder values. Copy to .env.
- .gitattributesNormalises line endings so Windows and Linux developers produce the same diffs.
- .gitignoreThe standard .NET ignore list: bin, obj, IDE folders, user files, plus your .env.
- AGENTS.mdInstructions for AI coding agents: commands, project layout, rules.
- CLAUDE.mdClaude Code's instructions file, often just a line importing AGENTS.md.
- compose.yamlLocal PostgreSQL, Redis and a mail catcher for development, started with docker compose up.
- Directory.Build.propsMSBuild settings applied to every project: framework, nullable, warnings as errors, analyzers.
- Directory.Packages.propsCentral package management: every NuGet version in one file, plus solution-wide analyzers.
- global.jsonPins the .NET SDK version used to build the repository.
- README.mdHow to run, test, migrate and deploy the API.
- Shop.slnxThe solution file in the new XML format, listing every project.
Learn more on Sefism
Roadmaps, cheat sheets and projects that go with ASP.NET Core Web API.
- Roadmap· Web API.NET developer roadmapC#, ASP.NET Core, EF Core, production-ready APIs
- Roadmap· C#Backend development roadmapAPIs, databases, auth, deploys
- Roadmap· Full stack with Angular.NET developer roadmapC#, ASP.NET Core, EF Core, production-ready APIs
- Roadmap· SQL ServerSQL and databases roadmapQueries, design, indexes, transactions
- Cheat sheet.NET developer cheat sheetC#, ASP.NET Core, EF Core, production-ready APIs.
- Cheat sheetBackend development cheat sheetAPIs, databases, auth, deploys.
- Cheat sheetSQL and databases cheat sheetQueries, design, indexes, transactions.
- FYP idea· IntermediateProduction-Ready ASP.NET Core API for Intercity Bus Seat BookingMost student APIs stop at CRUD. Build an intercity bus seat booking API in ASP.NET Core that is production-ready from day one: safe seat holds under heavy concurrency, health checks, rate limiting, OpenTelemetry traces and metrics, structured logging, problem details errors, migrations, integration tests with real databases and a load test for the Eid travel rush. Publish it as a template others can start from.
- FYP idea· IntermediatePharmacy Stock Ledger with Batch Expiry and FEFO DispensingA web-based stock ledger and billing counter for independent pharmacies that tracks every medicine by batch and expiry, sells loose tablets from strips correctly, and dispenses first-expiry-first-out. A final year project in healthcare retail software with real inventory correctness problems to solve.
See 10 moreShow fewer
- FYP idea· IntermediateSchool Report Card System with Configurable Grading Rules and Batch PDFsA web system for private schools to enter marks, apply their own grading and promotion rules, moderate results and generate hundreds of printable report cards in one batch. An intermediate final year project in education software with a real rules engine and a document generation pipeline.
- QuestionHow do I learn to read a large codebase when I can handle small projects but get lost in real ones?Nobody reads a large codebase from top to bottom. You follow one real path through it, such as a single request or button click, from entry point to database and back. Map what you find, ignore everything off that path for now, and repeat with a different path. Understanding builds in layers, and a first small change teaches more than a week of reading.
- QuestionHow do I learn low level design and design patterns as a student?Learn it in order: OOP used properly, then SOLID, then the everyday design patterns, then small systems built end to end with tests. Patterns only make sense once you have felt the problem they solve, so build a parking lot, a rate limiter and an expense splitter rather than memorising 23 diagrams.
- QuestionDo I need Docker and Kubernetes as a junior developer?Docker, yes: learn the basics, because nearly every team uses containers and you will be expected to run the project locally and read a Dockerfile. Kubernetes, mostly no: understand what it does and a few core terms, but deep Kubernetes can wait until your job or a DevOps direction needs it.
- QuestionHow do I learn to write clean code as a junior developer?Clean code is a set of habits, not a book you finish. Fix names, function size, flag arguments and error handling one habit at a time, let a formatter and linter settle style, learn to refactor in small steps behind tests, and keep a list of the review comments you get twice: that list is your personal curriculum.
- Resource· GuideASP.NET Core DocumentationMicrosoft's official documentation for ASP.NET Core, the cross-platform .NET framework for web apps and APIs. It covers minimal APIs and controllers, Razor Pages, MVC, Blazor, SignalR and gRPC, plus Entity Framework Core, security and identity, testing, performance and deployment, with a first tutorial for each app style. It suits C# developers building web back ends, and it is usually more current and accurate than third-party tutorials.
- Resource· GuideEntity Framework Core documentationThe official EF Core docs on Microsoft Learn: modelling entities and relationships, migrations, querying with LINQ, saving data, performance and database providers such as SQL Server and PostgreSQL. Free, current for EF Core 10, with a dedicated performance section every .NET developer should read.
- Resource· GuideAspire documentationThe official docs for Aspire, the open source, code-first tool for running, observing and deploying distributed apps. Learn the AppHost, the developer dashboard with OpenTelemetry logs, traces and metrics, and the standalone dashboard. Free, MIT licensed, version 13.6 as of September 2026.
- Resource· GuideTestcontainers for .NETOfficial docs for Testcontainers for .NET, the library that starts real databases, caches and brokers in Docker for your tests and removes them afterwards. Ready-made modules for SQL Server, PostgreSQL, Redis and more. Free and open source under MIT.
- Resource· GuideOWASP API Security Top 10The OWASP API Security Top 10 (2023 edition) lists the most critical security risks in APIs, led by broken object level authorisation, broken authentication and broken object property level authorisation. Each risk comes with attack scenarios and prevention advice. It suits anyone building or reviewing backends, because these flaws are common, easy to miss in code review and often invisible in normal testing.
Checked against 16 official sources, October 2026. If something has changed, the docs win.Show sourcesHide sources
- ASP.NET Core webapi template source (release/10.0)
- .NET SDK project and item templates (xunit, sln, buildprops)
- What's new in ASP.NET Core in .NET 10
- What's new in the SDK and tooling for .NET 10
- Configuration and the options pattern in ASP.NET Core
- Handle errors in ASP.NET Core APIs (IExceptionHandler, ProblemDetails)
- Policy-based and resource-based authorization in ASP.NET Core
- Rate limiting middleware in ASP.NET Core
- HybridCache library in ASP.NET Core
- Build resilient HTTP apps (Microsoft.Extensions.Http.Resilience)
- Health checks in ASP.NET Core
- EF Core migrations overview and bundles
- Integration tests in ASP.NET Core
- Aspire documentation (AppHost and ServiceDefaults)
- Testcontainers for .NET
- Common web application architectures (.NET guide)
Best practices and checklists for this stack
Picked from the other libraries by shared topics.
Best practices
See all- Node.js API Best PracticesBuild Node.js REST APIs that hold up in production: structure, validation, error handling, security headers, rate limits, logging, testing and graceful shutdown.
- Observability Best PracticesKnow when production is hurting users and why: SLOs, golden signals, metric naming and cardinality, structured logs, OpenTelemetry traces and burn-rate alerts.
- PostgreSQL Best PracticesDesign, index, query and run PostgreSQL well: data types, constraints, EXPLAIN, zero-downtime migrations, pooling, transactions, backups and roles.
Checklists
See all- Database Migration ChecklistCheck a schema or data migration before it ships: expand and contract, lock behaviour, online indexes, batched backfills, rehearsal on real data, backups, rollback, deploy order and monitoring.
- Production Readiness ChecklistCheck a service before it takes real traffic: ownership, SLOs, capacity, timeouts and retries, alerts, rollout and rollback, backups, security and on-call.
- API Security ChecklistCheck your REST or GraphQL API against the OWASP API Security Top 10: authentication, object authorization, rate limits, input validation, SSRF, CORS and logging.
Work with me
Stuck on something specific?
Writing only gets you so far. If you want an answer to your situation rather than the general case, book a session and we will work through it together. Sessions are free for approved Sefism members, and a few slots open each week.
- 1:1 Mentorship
- Fresh Graduate Mentorship
- Career Guidance
Brand deals, promos and partnerships: tauseeffayyaz@gmail.com