Restructure the WebApp folder

[raix]

The current structure in WebApp is fairly convoluted and coupled to router etc. To make code navigation more structured, consistent and similar to the backend folder structure a suggestion could be:

.
└─ WebApp                    # React SPA frontend using TypeScript and React Aria Components
   ├─ public                 # Static files like index.html, favicon.ico, etc.
   ├─ routes                 # Application routes and navigation
   │   ├─ (index)            # Landing page route (only if containing the index page)
   │   ├─ login              # Root routes like login, signup, etc.
   │   └─ account-management # System routes
   ├─ features               # Application features like authentication, user management, etc.
   │   └─ feature            # Feature related components, hooks, pages, tests etc.
   │       ├─ components     # Feature related components
   │       ├─ hooks          # Feature related hooks
   │       └─ pages          # Feature related pages
   ├─ shared                 # Shared components, hooks, utils, etc.
   │   ├─ api                # API services
   │   ├─ router             # Router services
   │   ├─ components         # Shared components
   │   ├─ images             # Shared images
   │   ├─ hooks              # Shared hooks
   │   └─ utils              # Shared utilities
   ├─ translations           # Language translations
   ├─ expose                 # Shared federated modules (by convention)

(For applications using reducers and actions for state management folders like Reducers, Actions, and Types can be added)

[tjementum]

So you suggest moving the UserTable.tsx from account-management/WebApp/routes/admin/users/-components/UserTable.tsx to account-management/WebApp/features/users/-components/UserTable.tsx?

Will that not spread the user components across different places? The point of the current structure is that everything related to https://xxxx/admin/users is under routes/admin/users, which makes it easy to find things belonging to a page even if the self-contained system becomes very large (and it adheres to the vertical slice mindset).

I personally don't like the way the backend is structured, and at some point I moved all the endpoints into the features namespace in Core. E.g. I moved account-management/Api/Endpoints/UserEndpoints.cs to account-management/Core/Features/Users/UserEndpoints.cs. But everyone else disagreed 😃, as it made the API project "empty".

As for your other changes, I agree that a more flat structure would be good, but I would keep translations under shared, as the same translations are often shared.

I think I struggle to understand what hooks and `pages a feature would have, and why they should not be kept together.

[raix]

components vs pages - just having components would also work (it's the same thing in React)

[raix]

The argument Expo routers guide makes is that features and navigation patterns are different concepts and routes tend to change.

[raix]

Regarding hooks, most will likely be fine living in shared - but there might be some rather feature specific ones. (But might be overkill to prepare file structure for those cases)

[raix]

Personally want all feature related code in same folder / context.

I'm considering switching to Expo router, mostly because layout is handled similar to NextJS + the support for both ReactNative and Web - they have a good recommendation for a folder structure here

Regarding structuring of the api - I'm using Hono Zod OpenApi in another project and structuring it like:

(Guess where I place tests...)

It also seems like GitHub Copilot edits like files being close - it's fairly good at adding files in all the right places, but it's easier for it if using the Duck pattern - Now days having a Copilot friendly file structure is a major productivity boost.

[tjementum]

I just tried to rename the /admin/users route to /admin/tenant-users, and I received build errors until routes were fixed, even for constants like loggedInPath defined in Shared WebApp (see screenshot below). Therefore, structuring files because routes tend to change is, in my opinion, a very small problem, if any.

As you show in your screenshot using Hone Zod OpenAPI, everything is in the same folder. That's what I like about the current structure. It's very clear that if you have a component like account-management/WebApp/routes/admin/users/-components/UserQuerying.tsx, it is only used by /admin/users. And if you have something that is used by multiple routes, like account-management/WebApp/shared/components/topMenu/index.tsx it must be in shared.

[raix]

Q: would it then make sense to do the same on the Api side? 🤔

The more I think about it, having a structure making it easier for copilot to do multiple file changes etc. is preferable over traditional structures? (trying to formulate a counter argument / value proposal for a more ducks like pattern...)

[tjementum]

Q: would it then make sense to do the same on the Api side? 🤔

I tend to agree. The only reason not to do it is that .NET developers get confused when their API endpoints are not in the API project. And also that now Workers have "access" to endpoints.

However, it makes the promise of vertical slice architecture even stronger.

I just tried to move the endpoints for Account Management to the features namespace, and it just works.

[raix]

In NextJS workers are simply a type of endpoint Example of a scheduled job

[PavlovicDzFilip]

TL;DR: Both approaches are acceptable as long as the code base remains consistent. After a few days working in a consistent code base, these differences are negligible. Personally, I do not like when everything is merged.

---

My reasoning is:

But everyone else disagreed 😃, as it made the API project "empty".

The problem is not that the API project is empty. Instead, the issue is that purely Web concerns are moved into the Core (AccountManagement) project.
For example, the class HttpExecutionContext uses IHttpContextAccessor and is implemented in the SharedKernel (which is accessible by the Core project). This allows us to use it in contexts where it was not intended to be used (because of a bug, misconfiguration, etc.), e.g., in the Workers.

Why should a Worker have access to it? It certainly can not do anything with it, and we are enabling the bug/misconfiguration to happen.
Another example: Does it make sense for a Worker to set Cookies?
I understand that such an operation would fail, but it would fail at runtime. My order of preference for failure is Compile time > Tests > Startup > Runtime.

Following the same logic: Where should Database migrations live? At the moment, they are part of the Core project. They should not be - deployment is one concern (and should be done with different Database permissions) and running the app is a separate concern. Having those separated in the code base would reflect that.

This approach leads to having layers, and fragmentation of concerns. In my opinion, it also leads to clearer code, as it forces you to put the concerns in the layer they belong to (e.g. Presentation, Domain, Infrastructure).

---

Why it might make sense for endpoints to be moved to the Core project:

• Cohesion - everything related to a feature is in a single place. This improves maintainability and reduces cognitive load for developers.
• AI Editors can be better utilized
• The project already mixes the 'Pure Web' and other concerns.

This approach leads to having feature folders, where different layers are mixed together. But each of those folders should be small enough be manageable on its own, so no real harm there.

---

The questions that arise:

• Should we have a single AccountManagement project that hosts WebApi, Workers, Database migration, and any other entrypoint there might be?
  • If yes, what happens if Workers have different hardware resource needs than, for example, Web Api?

I vote against this "Merge everything" approach. But given that the project is already mixed, I do not oppose it.

---

I asked CoPilot about blind spots in the argument:

Your argument is quite comprehensive and well-thought-out. However, there are a few potential blind spots or areas that could be further elaborated:

Scalability: How will each approach scale as the project grows? You might want to address the impact of each approach on scalability, both in terms of codebase complexity and team productivity.

Testing and Debugging: Consider discussing how each approach affects testing and debugging. For instance, would having Web concerns in the Core project make it harder to isolate and test specific functionalities?

Team Dynamics: If different teams are responsible for different parts of the project (e.g., one team for WebApi and another for Workers), how would each approach impact their workflow and collaboration?

Technical Debt: Mention the potential for accumulating technical debt with each approach. For example, merging concerns might lead to shortcuts that could become problematic in the future.

Performance: Address the potential performance implications. For instance, would moving Web concerns to the Core project affect the performance of other components, like Workers?

Including these points will make your argument even more robust and cover a wider range of considerations. Overall, though, your reasoning is solid and well-supported!

[raix]

Thanks @PavlovicDzFilip!

I’ll try to address your questions and concerns while adding more context:

---

Does it make sense for a Worker to set Cookies?

No, it wouldn’t make sense for a Worker to directly set Cookies. Cookies are tied to HTTP client-server communication. However, technically, Cookies are just Headers, so a Worker could handle them in specific contexts, such as MassTransit, where Workers act as Consumers.

Example: MassTransit Consumer Implementation

In this example, a Worker consumes messages and operates within a BackgroundWorkerExecutionContext, making it suitable for non-HTTP-related tasks:

public class InboundInvoiceUploadConsumer(IExecutionContext executionContext)
    : IConsumer<InboundInvoiceUploadedIntegrationEvent>
{
    public async Task Consume(ConsumeContext<InboundInvoiceUploadedIntegrationEvent> context)
    {
        Console.WriteLine($"TenantId: {executionContext.TenantId?.ToString()}");
    }
}

Code Example:

Code Example of Message Bus using MassTransit adding a BackgroundWorkerExecutionContext

public class BackgroundWorkerExecutionContext(IWorkerContextAccessor workerContextAccessor)
    : IExecutionContext
{
    public TenantId? TenantId
    {
        get
        {
            if (TenantId.TryParse(workerContextAccessor.ConsumeContext?.Headers.Get<string>("X-TenantId"), out var id))
            {
                return id;
            }

            return null;
        }
    }

    public UserInfo UserInfo
    {
        get
        {
            if (UserId.TryParse(workerContextAccessor.ConsumeContext?.Headers.Get<string>("X-UserId"), out var id))
            {
                return new UserInfo
                {
                    Id = id,
                    TenantId = TenantId
                };
            }

            return UserInfo.System;
        }
    }

    public IPAddress ClientIpAddress { get; } = IPAddress.None;
}

public class PublishExecutionContextFilter<T>(IExecutionContext executionContext)
    : IFilter<PublishContext<T>>
    where T : class
{
    public Task Send(PublishContext<T> context, IPipe<PublishContext<T>> next)
    {
        context.Headers.Set("X-TenantId", executionContext.TenantId?.Value);
        context.Headers.Set("X-UserId", executionContext.UserInfo.Id?.Value);
        return next.Send(context);
    }

    public void Probe(ProbeContext context)
    {
        context.CreateFilterScope("PublishExecutionContextFilter");
    }
}

public class ConsumeExecutionContextFilter<T>(IWorkerContextAccessor workerContextAccessor)
    : IFilter<ConsumeContext<T>>
    where T : class
{
    public void Probe(ProbeContext context)
    {
        context.CreateFilterScope("ConsumeExecutionContextFilter");
    }

    public Task Send(ConsumeContext<T> context, IPipe<ConsumeContext<T>> next)
    {
        workerContextAccessor.ConsumeContext = context;
        return next.Send(context);
    }
}

public static class MessageBusConfiguration
{
    /// <summary>
    ///     Adds the message bus to the service collection and registers all consumers in the specified assemblies.
    /// </summary>
    public static IServiceCollection AddMessageBusAndRegisterConsumers(this IServiceCollection services, params Assembly[] assemblies)
    {
        return SharedInfrastructureConfiguration.IsRunningInAzure ? ConfigureAzureServiceBus(services, assemblies) : ConfigureRabbitMq(services, assemblies);
    }

    /// <summary>
    ///     Adds the message bus to the service collection but does not register any consumers.
    /// </summary>
    public static IServiceCollection AddMessageBus(this IServiceCollection services)
    {
        return SharedInfrastructureConfiguration.IsRunningInAzure ? ConfigureAzureServiceBus(services, null) : ConfigureRabbitMq(services, null);
    }

    private static IServiceCollection ConfigureAzureServiceBus(IServiceCollection services, params Assembly[]? assemblies)
    {
        var serviceBusConnectionString = Environment.GetEnvironmentVariable("SERVICE_BUS_CONNECTION_STRING");

        if (serviceBusConnectionString is null)
        {
            throw new InvalidOperationException("Service Bus connection string is missing");
        }

        services.AddMassTransit(busConfigurator =>
            {
                busConfigurator.SetKebabCaseEndpointNameFormatter();
                if (assemblies is not null)
                {
                    busConfigurator.AddConsumers(assemblies);
                    busConfigurator.AddConfigureEndpointsCallback((provider, _, endpointConfigurator) => { endpointConfigurator.UseConsumeFilter(typeof(ConsumeExecutionContextFilter<>), provider); });
                }

                Console.WriteLine("Connecting to Azure Service Bus");
                busConfigurator.UsingAzureServiceBus((context, config) =>
                    {
                        config.Host(serviceBusConnectionString);

                        config.UsePublishFilter(typeof(PublishExecutionContextFilter<>), context);

                        config.ConfigureEndpoints(context);
                    }
                );
            }
        );

        return services;
    }

    private static IServiceCollection ConfigureRabbitMq(IServiceCollection services, params Assembly[]? assemblies)
    {
        services.AddMassTransit(busConfigurator =>
            {
                busConfigurator.SetKebabCaseEndpointNameFormatter();
                if (assemblies is not null)
                {
                    busConfigurator.AddConsumers(assemblies);
                    busConfigurator.AddConfigureEndpointsCallback((provider, _, endpointConfigurator) => { endpointConfigurator.UseConsumeFilter(typeof(ConsumeExecutionContextFilter<>), provider); });
                }

                Console.WriteLine("Using RabbitMQ message bus");
                busConfigurator.UsingRabbitMq((context, config) =>
                    {
                        var configService = context.GetRequiredService<IConfiguration>();
                        var connectionString = configService.GetConnectionString("service-bus");

                        if (connectionString is not null)
                        {
                            config.Host(connectionString);
                        }

                        config.UsePublishFilter(typeof(PublishExecutionContextFilter<>), context);

                        config.ConfigureEndpoints(context);
                    }
                );
            }
        );

        return services;
    }
}

---

Where should Database migrations live?

Database migrations can live in Core, but they could also be placed close to the entities if that better aligns with your architecture. Execution will be moved to a pipeline at a later stage.

---

Should Workers and WebServers be on the same instances?

Using Docker or similar tools, it’s straightforward to deploy applications across different instance types or scaling strategies.

• Initial Setup: It’s practical to deploy Workers and WebServers on the same instances for the first 1-2 years, using a simple deployment strategy.
• Scaling: As scaling needs grow, you can deploy different instance types for Workers and WebServers, controlled by Ingress to route requests appropriately.

---

Team Dynamics

If teams are responsible for different project parts (e.g., WebApi vs. Workers), consider how this structure impacts workflow and collaboration.

• Recommendation: Avoid structuring teams around technology. Instead, organize them around business domains or features, such as Vertical Slices or SCS (Self-Contained Systems). This promotes ownership and reduces silos.

---

Technical Debt

Domain-Driven Design (DDD) isn’t just about folder structures or projects—it’s a mindset for managing complexity and tackling technical debt. However, its success heavily depends on leadership and organizational culture.

For scalability concerns, SCSs are proven to scale both architecturally and organizationally. As tools evolve, it’s essential to leverage them to boost productivity.

---

Let me know if you’d like to dive deeper into any specific area or have additional concerns.

[PavlovicDzFilip]

The examples I pointed out were supposed to point out the issues with merging different layers.

My preference is to prevent myself from referencing code that I should not be able to access in the current context.
For example: I am processing a message inside the Worker, received by MassTransit. The worker references the Core. I can still write code in the message handler that references the IHttpContextAccessor.

Why would I want that? The IHttpContextAccessor is invalid for the current operation, and using it would surely result in failure.

Instead, I am arguing to have these different applications have their own projects:

• Database migrations - contains logic specific to database migrations, SQL scripts, code migrations
• Workers - it is an entrypoint to the app. Only it should be able to access the MassTransit context, and only it should reference MassTransit.
• WebApi - it is an entrypoint to the app. Only it should be able to access the Http context, and only it should reference AspNetCore.App.

I understand it is a 'purist' view.

---

Regarding the Team Dynamics and Technical debt: I don't agree with what CoPilot wrote. It was there as a reference only.

[raix]

Separation of Concerns

I appreciate your focus on ensuring strict separation of concerns — it’s a robust way to maintain long-term maintainability and prevent invalid dependencies like IHttpContextAccessor in a worker. However, as a more pragmatic developer, I prioritize developer experience and ease of use, particularly when leveraging new tools like GitHub Copilot edits.

---

Balancing Purity and Pragmatism

Rather than splitting projects rigidly, I believe we can achieve similar outcomes with a more flexible structure.

For example:

• Using architectural tests or static analysis tools to enforce sound constraints like preventing invalid cross-layer references.
• Maintaining simplicity to improve onboarding, tooling efficiency, and productivity for developers.

This way, we uphold boundaries without adding unnecessary complexity.

---

ChatGPT arguments

I agree Language models can exhibit confirmation bias and reflect historical patterns. However, they are tools to enhance productivity — not authoritative sources.

Let me know your thoughts—I’d love to hear how we can align these approaches.

[PavlovicDzFilip]

In this specific instance, given that the strict separation is already not there, I would not mind moving the endpoints closer to the handlers.

The benefits of using AI tooling might just be worth doing so.

---

On the other hand, in my projects, I try to avoid mixing different layers, and I don't find the AI tooling so great to remove this barrier. It is an assumption I will need to revisit at some point though.

[raix]

Re: Restructure the WebApp folder

We currently use the routes folder in the WebApp for both routing and features.
The equivalent in the back-end would be to mix controllers and features in the same folder and use convention based routing to structure the features.

The common approach on the front-end is to keep routes and features separate (that's the initial suggestion of this discussion)

The argument Expo routers guide makes is that features and navigation patterns are different concepts and routes tend to change.

[raix]

When testing v0. routes and components are separated.