Structuring a .NET Core 9 Blazor + API Architecture for Microservices Readiness and Best Practices

Question

Structuring a .NET Core 9 Blazor + API Architecture for Microservices Readiness and Best Practices

Laurent Guigon 311

Hello,

I am working on a wiki-style encyclopedic resource application designed to centralize and organize documentation related to the universe of my fantasy novel. This project is personal and primarily has a pedagogical purpose (training myself on modern architectures and anticipating a future move to microservices). At the same time, I want to obtain a robust and scalable foundation to avoid having to rewrite everything at each new iteration.

Some key points about my context:

Limited budget: my goal is to keep costs around €10/month on Azure, which excludes for now the use of multiple databases or complex container orchestration.
Minimal Azure infrastructure: a single App Service and a single database to host the entire solution.
Small team: I am the sole developer (“one-man team” approach), although I occasionally benefit from feedback or virtual assistants.
Time constraint: this is a long-term project, carried out in irregular phases depending on my availability.
Current usage: the application is almost exclusively used by myself, with possibly two or three secondary users. However, I want to anticipate scalability for broader use in the medium term.
History: this is the eighth version of my project, started several years ago. Each version allowed me to experiment with the evolution of .NET (the first iteration going back to .NET 3.5).
Main objective: to have a modular and scalable architecture, avoiding complete rewrites at every technological change.
Architectural vision: remain for now on an organized monolith, but ensure that the structure is “microservices ready” for a future evolution.
Design principles: follow DRY and SOLID best practices to obtain a healthy and maintainable foundation.

Chosen Software Architecture

The implemented architecture is based on a modular monolith. It remains simple to respect my current constraints but is designed to be able to evolve towards a distributed architecture if necessary.

Shared/Base Layer

A common project gathers:

Interfaces and cross-cutting abstractions (e.g., DbContext, initialization).
Elements related to dependency injection and utilities. This base ensures consistency and reduces redundancy between domains.

Business Domains

Each functional domain is isolated in a dedicated project:

Currently, only the Content domain is developed (content management, with front-office and back-office).
- A topic has a mandatory summary and a set of chapters.
- Each chapter contains one or more sections.
In the future, other domains will follow, such as Audit to log all changes.

Each domain project contains:

Repositories (data access)
Business services
Fluent API (DbContext and relationship configuration)

Business Models

The EF Core entities defined in the Model projects are used directly up to the Blazor front-end:

This choice avoids, for now, the multiplication of DTOs or ViewModels.
Since the entities already reflect what must be displayed, this approach keeps the project lighter and more readable.

Data Seeders

Two types of seeders are planned:

Actual Data Seeders (import of real data)
Dummy Data Seeders (generation of test data) They can be executed independently via PMC or via YAML pipelines.

Unified API

A single API gathers all the functionalities exposed by the domains:

It acts as a gateway between the Blazor front-end and the business logic.
This choice simplifies maintenance and remains compatible with a future evolution toward a microservices split.

Blazor Front-End

The front-end is developed in Blazor, which directly consumes the API:

This architecture allows a clear separation between logic and presentation.
It remains extensible: the front could be rewritten or replaced without affecting the business logic.

Global Breakdown

                              +------------------+
                              |   Front-End      |
                              |   Blazor (UI)    |
                              +------------------+
                                       |
                                       V
                              +------------------+
                              |      API         |
                              |   (unified)      |
                              +---------+--------+
                                        |
                                        V
        ---------------------------------------------------------
        |                                                       |
        V                                                       V
+---------------+                               +---------------+
|   Domain 1    |                               |   Domain 2    |
| (Services,    |                               | (Services,    |
|  Repos,       |----                       ----|  Repos,       |
|  DbContext,   |    |                      |   |  DbContext,   |
|  Fluent API)  |    |                      |   |  Fluent API)  |
+------+--------+    |                      |   +------+--------+
       |             |                      |          |
       V             |                      |          V
+---------------+    |                      |   +---------------+
|   Model 1     |    |                      |   |   Model 2     |
| (EF Entities) |    |                      |   | (EF Entities) |
+---------------+    |                      |   +---------------+
                     |                      |
                     \___________ __________/
                                 |
                                 V
                  +-----------------------------+
                  |      Shared / Base Layer    |
                  | (Interfaces, abstractions   |
                  |  DbContext, DI, utilities)  |
                  +-----------------------------+

Questions and Validation Points

Choice of Blazor mode

For now, Blazor Server seems the most suitable choice (cf. Patrick God’s resources on YouTube).
Question: to what extent will it be possible to migrate later to Blazor Auto (Server + WASM)?
What constraints should I anticipate today to keep this option open?

Security and Account Management

I want to use Identity with individual accounts.
With the architecture separating the front (Blazor) and the back (API), I wonder where to place the security logic.
Current assumption: authentication via JWT, with validation on the API side.
Questions:
1. Should I create an Accounts domain with specific controllers to manage users and roles?
2. Or should I keep the Identity implementation on the Blazor side, and only expose an API for administration (locking, role assignment, etc.)?

Relevance of the Current Architecture

I chose a modular monolith with separate projects per domain.
Objectives:
1. Pedagogical (learning a “microservices ready” approach)
2. Practical (being able to replace the front without rewriting everything)
Question: is this choice relevant, or is it disproportionate (over-engineered) for my context?

Direct Use of Entities

My business entities directly reflect what must be displayed.
I therefore do without DTOs or ViewModels.
Question: is this acceptable in a project of this type, or should I plan for a DTO layer from the start?

Thanks

Thank you in advance for the time you will take to read this detailed version and share your feedback. Your advice is very valuable for validating my choices and progressing in this project.

Laurent Guigon 311 Reputation points

2025-09-04T10:47:44.0166667+00:00
My first message was deleted when I edited it... May be because of emojis.

I’d like to add a few more points for clarification and to get more targeted feedback:

Blazor Rendering Mode

For the start, I am planning to use Blazor Server, as it seems the most suitable for my current usage and small number of users.

However, I am wondering whether it would make sense to go directly with Blazor Auto (Server + WASM). Would this add unnecessary complexity at the beginning, or could it make future migration easier?

Security Implementation

I plan to use Identity with individual accounts.

Given that the front-end (Blazor) and the back-end (API) are separate, I am not sure where the security logic should be implemented. Should the API have dedicated controllers for accounts management, or is it better to keep Identity scaffolding on the Blazor side and only expose administrative endpoints?

I also want to ensure proper JWT usage between front and back. Any practical guidance on this setup would be very helpful.

Project Structure vs. Modularity

Currently, I have a modular monolith with separate projects per domain. This allows me to keep the architecture clean and “microservices ready” for the future.

My question is whether, given my current constraints (solo development, small budget, few users), it would be simpler to use a single Blazor project with everything included, even if I lose some modularity. Would this be a reasonable trade-off at this stage, or would it create more problems later?

I appreciate any advice or experiences you can share regarding these points, especially from people who have faced similar choices in early-stage projects with limited resources.
Deleted

This comment has been deleted due to a violation of our Code of Conduct. The comment was manually reported or identified through automated detection before action was taken. Please refer to our Code of Conduct for more information.
Deleted

This comment has been deleted due to a violation of our Code of Conduct. The comment was manually reported or identified through automated detection before action was taken. Please refer to our Code of Conduct for more information.

Laurent Guigon 311

Hello,

I wanted to share the proof-of-concept I have started for the Shared layer. This project is intended to centralize abstractions and contracts for Services and Repositories across each domain, avoiding duplication and keeping a clean architecture.

At this stage, this is only a P.O.C. and not yet integrated into the main solution. The idea is not to have the API depend on Shared directly, but to provide a foundation that each domain project can use consistently.

Here are the extracts I have prepared:

Generic repository contract:

using System;
using System.Collections.Generic;
using System.Linq.Expressions;
using System.Threading.Tasks;

namespace EncyclOniria.Shared.Contracts
{
    public interface IRepository<TEntity> where TEntity : class
    {
        Task<TEntity?> GetByIdAsync(Guid id);
        Task<IEnumerable<TEntity>> GetAllAsync();
        Task<IEnumerable<TEntity>> FindAsync(Expression<Func<TEntity, bool>> predicate);
        Task AddAsync(TEntity entity);
        void Update(TEntity entity);
        void Remove(TEntity entity);
        Task<int> SaveChangesAsync();
    }
}

Connection string abstraction:

namespace EncyclOniria.Shared.Contracts
{
    public interface IConnectionStringProvider
    {
        string GetConnectionString(string domain); // ex: "Content" (get from env. vars) 
    }
}

Environment-based implementation:

using EncyclOniria.Shared.Contracts;

namespace EncyclOniria.Shared.Contracts
{
    public class EnvironmentConnectionStringProvider : IConnectionStringProvider
    {
        public string GetConnectionString(string domain)
        {
            var envName = $"CONNSTR_{domain?.ToUpperInvariant() ?? "DEFAULT"}";
            var cs = Environment.GetEnvironmentVariable(envName);
            if (string.IsNullOrWhiteSpace(cs))
                throw new InvalidOperationException($"Missing connection string for domain '{domain}'. Expected env var '{envName}'.");

            return cs;
        }
    }
}

Base DbContext to centralize common behaviors:

using Microsoft.EntityFrameworkCore;

namespace EncyclOniria.Shared.Data
{
    public abstract class BaseDbContext : DbContext
    {
        public BaseDbContext(DbContextOptions options) : base(options) { }

        protected override void OnModelCreating(ModelBuilder modelBuilder)
        {
            base.OnModelCreating(modelBuilder);
            // Example: apply cross-cutting conventions
            // modelBuilder.ApplyConventionsFromAssembly(...);
        }
    }
}

Design-time DbContext factory for migrations (Content domain):

using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Design;
using Microsoft.Extensions.Configuration;
using System.IO;

namespace EncyclOniria.Content.Data
{
    public class DesignTimeContentDbContextFactory : IDesignTimeDbContextFactory<ContentDbContext>
    {
        public ContentDbContext CreateDbContext(string[] args)
        {
            var builder = new DbContextOptionsBuilder<ContentDbContext>();

            var config = new ConfigurationBuilder()
                .SetBasePath(Directory.GetCurrentDirectory())
                .AddJsonFile("appsettings.json", optional: true)
                .AddEnvironmentVariables()
                .Build();

            var cs = config.GetConnectionString("ContentDb") 
                     ?? Environment.GetEnvironmentVariable("CONTENT_DB_CONNECTION")
                     ?? "DataSource=:memory:";

            builder.UseSqlServer(cs);
            return new ContentDbContext(builder.Options);
        }
    }
}

This P.O.C. is mainly to avoid duplication and start building a modular, maintainable foundation.

2 answers

Your answer

Laurent Guigon 311 Reputation points

2025-09-04T10:47:44.0166667+00:00

My first message was deleted when I edited it... May be because of emojis.

I’d like to add a few more points for clarification and to get more targeted feedback:

Blazor Rendering Mode

For the start, I am planning to use Blazor Server, as it seems the most suitable for my current usage and small number of users.

However, I am wondering whether it would make sense to go directly with Blazor Auto (Server + WASM). Would this add unnecessary complexity at the beginning, or could it make future migration easier?

Security Implementation

I plan to use Identity with individual accounts.

Given that the front-end (Blazor) and the back-end (API) are separate, I am not sure where the security logic should be implemented. Should the API have dedicated controllers for accounts management, or is it better to keep Identity scaffolding on the Blazor side and only expose administrative endpoints?

I also want to ensure proper JWT usage between front and back. Any practical guidance on this setup would be very helpful.

Project Structure vs. Modularity

Currently, I have a modular monolith with separate projects per domain. This allows me to keep the architecture clean and “microservices ready” for the future.

My question is whether, given my current constraints (solo development, small budget, few users), it would be simpler to use a single Blazor project with everything included, even if I lose some modularity. Would this be a reasonable trade-off at this stage, or would it create more problems later?

I appreciate any advice or experiences you can share regarding these points, especially from people who have faced similar choices in early-stage projects with limited resources.
Deleted

This comment has been deleted due to a violation of our Code of Conduct. The comment was manually reported or identified through automated detection before action was taken. Please refer to our Code of Conduct for more information.

Answer 1

Bruce (SqlWork.com) 80,091 Volunteer Moderator

Blazor Rendering Mode

Blazor WASM can not access any server resources directly, like call a database. If you want to be able to migrate from server to WASM, then have a separate UI website, and a separate Webapi website. You will not have to rewrite the calls to the API.

it is generally best practice to do this split. the webapi project does not need to be exposed to the public and reduces the attack vector.

Security Implementation

if you use Individual accounts, there is no builtin JWT support as it is razor page cookie authentication. also only Blazor server is supported out of the box. You can use a custom openid server like Identity Server (https://duendesoftware.com/products/identityserver/) which you can integrate with individual identity. You can also roll you own, but unless you r really good understanding of the security issues you should buy the solution.

if you stand front-end UI to back-end WebApi you will need to decide how user credentials are passed, and how the backend validates calls from the front end.

Project Structure vs. Modularity

if you code as a monolith single deployed application, extra care will need to be taken to be sure lower code objects do not leak, and of course you will be using direct calls instead of webapi to call the service layers.

your best bet you be to create injectable interface to call the api. then in the future you can rewrite the a webapi implementation.

you should create an abstract api project to be injected. it should have its own namespace. it should have no references to the lower api services, but rather define its own request response objects. If you define the domain entities here rather than formal request / response objects, don’t include the db context, that only belongs in the service layer. Also no entity method can reference a service layer api or object. This is why it can not have a reference to any service layer. A service layer can reference the api project.

Of then you create a call interface variant of the api project. this will have a reference to api interfaces and lower service layers.

Deleted

This comment has been deleted due to a violation of our Code of Conduct. The comment was manually reported or identified through automated detection before action was taken. Please refer to our Code of Conduct for more information.
Deleted

This comment has been deleted due to a violation of our Code of Conduct. The comment was manually reported or identified through automated detection before action was taken. Please refer to our Code of Conduct for more information.
Deleted

This comment has been deleted due to a violation of our Code of Conduct. The comment was manually reported or identified through automated detection before action was taken. Please refer to our Code of Conduct for more information.
Laurent Guigon 311 Reputation points

2025-09-05T12:35:39.0633333+00:00
Hello,

Following up on my previous message introducing the Shared layer P.O.C., I wanted to discuss the architecture choices and get feedback on whether they are appropriate for my project.

Current Understanding

Based on the advice received:

Blazor Server + unified API + separate .csproj per domain seems to be a good fit for my current needs. The idea is that Blazor Server will still use a Web API, which allows future scalability and keeps the architecture clean.

Shared layer:

This layer is intended for centralizing abstractions for Services and Repositories in each domain.

It is not used by the API directly, but each domain can leverage it to follow DRY and SOLID principles.

The P.O.C. I shared shows the main contracts and the base DbContext implementation.

Security / JWT:

I usually use Identity with cookie-based authentication in standard Blazor Server projects (all layers in a single project, as in most tutorials).

For this project, I have decided to implement JWT from the start, even on Server, to prepare for a possible future migration to WASM.

This decision makes it almost mandatory to create immediately a UserManagement domain (or Account domain, name TBD) to manage users, roles, and authentication.

I have found resources showing how to integrate JWT with Blazor Server:

JWT with Blazor Server – Video 1

JWT with Blazor Server – Video 2

Questions / clarifications:

I did not fully understand the part about creating an abstract API project to be injected:

"it should have its own namespace, have no references to the lower API services, define its own request/response objects. If you define domain entities here instead of formal request/response objects, don’t include DbContext, and no entity method can reference service layer objects."

Could you clarify the benefits and recommended implementation for this in my modular monolith?

Overall, I would like confirmation that the combination of:

Modular monolith

Separate .csproj per domain

Shared layer for Service/Repository abstractions

Unified API for front-end consumption

JWT for authentication (with a dedicated UserManagement domain)

is a relevant and appropriate architecture for my scenario, considering my current constraints and future evolution goals.

Thank you in advance for your feedback and guidance. Your advice is extremely valuable to help me validate these architectural decisions and move forward with confidence.

Answer 2

Bruce (SqlWork.com) 80,091 Volunteer Moderator

as you are using a single website hosting your application, you want layers.

UI layer project - Blazor app code
API layer interface project - used by the UI layer to talk to the business layer. the layer should be injected into the blazor app code via services. This project will define messages passed between the UI and API and also interface methods. The UI should only call methods defined in this layer, never any lower layer or reference a class in a lower layer.
API layer implementation project - this is an implementation of the API layer that directly calls the service layers. In the future you can implement a version that calls a webapi. you should have a build step that copies this library and dependencies to the blazor app project. and use Activator.CreateInstance() when defining the service instance
server layer projects. this is where your domain services and repositories are defined. It's important that the UI layer can not directly access the service layers or repositories.

while you can find online examples to roll you own JWT support, they generally are POC's and not very secure. You will need to study JWT security and verify the code is secure.

Laurent Guigon 311 Reputation points

2025-09-08T08:22:54.43+00:00
Hello, thank you very much for your detailed explanation. Here is how I understand the architecture now. Could you tell me if this structure holds up and if my choices seem relevant to you?

Planned Structure

1. DomaineBase (shared project) This project would centralize common abstractions and reusable code for all domain projects (e.g., base repositories, patterns, common exceptions, etc.). My idea is to use this layer to avoid code duplication across different domains. It should also provide shared logic necessary for the seeders to initialize the database. Do you think this is a good idea, or would you advise against this approach?

2. Domain Projects (one per business domain, e.g., Domain.Content, Domain.Account)

Entities

Fluent API / DbContext

Repositories (inheriting from DomaineBase abstractions if needed)

Business services

Tests (in separate projects)

I understand that the UI and API should never use domain entities directly.

3. API Layer Interface

Defines DTOs / view models

Defines service interfaces exposed to the UI

4. API Layer Implementation

Implements the interfaces defined above

Contains mapping logic between DTOs and domain entities

Calls the business services

5. API (ASP.NET Core WebAPI)

Hosts controllers

Configures dependency injection (services, repositories, etc.)

Reads environment variables (connection strings, JWT configuration, etc.)

Integrates JWT authentication and authorization

6. UI (Blazor Server for now)

Depends only on the API Layer Interface

Services are injected into Blazor components

7. Satellite Projects

Seeders (per domain, using shared abstractions from DomaineBase)

Unit and integration tests

Immediate next step: Domaine.Account

Since I am implementing JWT from the start, it seems necessary to immediately create the Account domain. This domain will manage user entities, authentication logic, and roles/permissions.

Security aspect

I am used to using cookie authentication in Blazor Server-only apps, but because I want to anticipate a possible move to WASM, I decided to start directly with JWT. I will follow a tutorial I found to implement it, but you mentioned that many JWT examples are simple POCs and not necessarily secure.

Do you have any recommendations for testing and validating a JWT implementation?

Are there best practices, tools, or validation steps you would recommend before moving further?

Additional question

When creating the projects, I was thinking:

not to check the “Individual Accounts” option in the Blazor UI project,

and directly add references to the domain project DLLs in my Domain layer.

Is this the correct approach?

Does this structure seem solid overall? And especially, what do you think about introducing the DomaineBase layer – is this a good design, or do you see risks or compromises with this approach?Here’s the English translation of your message, ready to post on the forum:

Hello, thank you very much for your detailed explanation.
Here is how I understand the architecture now. Could you tell me if this structure holds up and if my choices seem relevant to you?

Planned Structure

1. DomaineBase (shared project)
This project would centralize common abstractions and reusable code for all domain projects (e.g., base repositories, patterns, common exceptions, etc.).
My idea is to use this layer to avoid code duplication across different domains. It should also provide shared logic necessary for the seeders to initialize the database.
Do you think this is a good idea, or would you advise against this approach?

2. Domain Projects (one per business domain, e.g., Domain.Content, Domain.Account)

Entities

Fluent API / DbContext

Repositories (inheriting from DomaineBase abstractions if needed)

Business services

Tests (in separate projects)

I understand that the UI and API should never use domain entities directly.

3. API Layer Interface

Defines DTOs / view models

Defines service interfaces exposed to the UI

4. API Layer Implementation

Implements the interfaces defined above

Contains mapping logic between DTOs and domain entities

Calls the business services

5. API (ASP.NET Core WebAPI)

Hosts controllers

Configures dependency injection (services, repositories, etc.)

Reads environment variables (connection strings, JWT configuration, etc.)

Integrates JWT authentication and authorization

6. UI (Blazor Server for now)

Depends only on the API Layer Interface

Services are injected into Blazor components

7. Satellite Projects

Seeders (per domain, using shared abstractions from DomaineBase)

Unit and integration tests

Immediate next step: Domaine.Account

Since I am implementing JWT from the start, it seems necessary to immediately create the Account domain.
This domain will manage user entities, authentication logic, and roles/permissions.

Security aspect

I am used to using cookie authentication in Blazor Server-only apps, but because I want to anticipate a possible move to WASM, I decided to start directly with JWT.
I will follow a tutorial I found to implement it, but you mentioned that many JWT examples are simple POCs and not necessarily secure.

Do you have any recommendations for testing and validating a JWT implementation?

Are there best practices, tools, or validation steps you would recommend before moving further?

Additional question

When creating the projects, I was thinking:

not to check the “Individual Accounts” option in the Blazor UI project,

and directly add references to the domain project DLLs in my Domain layer.

Is this the correct approach?

Does this structure seem solid overall?
And especially, what do you think about introducing the DomaineBase layer – is this a good design, or do you see risks or compromises with this approach?
Bruce (SqlWork.com) 80,091 Reputation points Volunteer Moderator

2025-09-10T15:40:32.74+00:00

the DomaineBase layer is fine. you should always refactor common code to its own library.

when you add individual accounts to a blazor server or razor page project it adds the cookie based razor page based library that support registration, login, password reset, etc. it also includes the entity framework store code to access the identity database.

as you are recoding all this to token based (and probably Blazor rather than razor page), you probably want create a sample project and scaffold all the pages. this will give you a project to port.

you may want to create a razor project identity project used for registering, etc. and only add JWT login support to the Blazor app.
Laurent Guigon 311 Reputation points

2025-09-11T15:05:31.64+00:00
Hello,

Thank you for your previous explanations, they helped me clarify the structure. I would now like to present my functional need more precisely, to make sure I choose the right approach for authentication and authorization.

My functional requirements in summary:

A protected API, able to identify if a user is logged in and what roles they have.

The ability to implement fine-grained authorization, for example using [Authorize(Roles=...)] attributes or custom policies.

The ability to track the author of modifications (store in the database the GUID of the user performing the action).

A solution that remains evolvable, especially if my UI later becomes mixed (Blazor Server + Blazor WASM) and if I move towards a microservices architecture in the future.

In addition, unless I’m mistaken, the frontend should not directly access the database. That means I would probably need a dedicated API for account management (creation, login, retrieving user info, roles, etc.), correct?

If you had to implement this authentication/authorization system yourself in a project like mine, which solution would you choose?

A system fully based on JWT for all communications?

A hybrid approach (Identity cookies for account management and JWT for API calls)?

Or another architecture that I might not have considered, as long as it is free, compatible with a future microservices migration, and follows best practices?

Thank you in advance for your advice.

Share via

Structuring a .NET Core 9 Blazor + API Architecture for Microservices Readiness and Best Practices

Some key points about my context:

Chosen Software Architecture

Shared/Base Layer

Business Domains

Business Models

Data Seeders

Unified API

Blazor Front-End

Global Breakdown

Questions and Validation Points

Choice of Blazor mode

Security and Account Management

Relevance of the Current Architecture

Direct Use of Entities

2 answers

Current Understanding

Your answer