> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aspfox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Project Structure

> What every folder and project in the scaffolded codebase is responsible for.

## Folder tree

After scaffolding with `dotnet new aspfox -n Acme`, you get this structure:

```
Acme/
├── src/
│   ├── Acme.Api/                  # ASP.NET Core Web API host
│   ├── Acme.Application/          # CQRS commands, queries, handlers, interfaces
│   ├── Acme.Domain/               # Entities, value objects, enums, constants
│   └── Acme.Infrastructure/       # EF Core, Redis, Stripe, Resend, Hangfire
├── frontend/                      # React + TypeScript frontend
│   ├── src/
│   │   ├── features/              # Feature-based modules (auth, tenants, billing…)
│   │   ├── components/            # Shared UI components
│   │   ├── hooks/                 # Custom React hooks
│   │   ├── lib/                   # axios client, queryClient, constants, utils
│   │   └── types/                 # TypeScript type definitions
│   ├── index.html
│   ├── vite.config.ts
│   └── tailwind.config.ts
├── tests/
│   └── Acme.Tests/                # xUnit unit and integration tests
├── docker-compose.yml             # Local development services
├── docker-compose.prod.yml        # Production Docker Compose
├── Makefile                       # Dev workflow commands
├── .env.example                   # Environment variable template
└── Acme.sln
```

## Backend projects

### Acme.Domain

The innermost layer. Contains entities, value objects, enums, domain constants, and domain exceptions. Has no dependencies on any other project or NuGet package except `Microsoft.Extensions.Logging.Abstractions`.

**What it contains:** `User`, `Tenant`, `Subscription`, `Invitation`, `RefreshToken`, `Notification`, and all other domain entities. Permission constants in `Permissions.cs`. Email enum values in `EmailTemplate.cs`.

**What it cannot reference:** Entity Framework Core, ASP.NET Core, MediatR, or anything else from the infrastructure or presentation layer. If it needs to reference it, it belongs somewhere else.

### Acme.Application

The use-case layer. Contains all CQRS commands, queries, their handlers, validators, and DTOs. Defines interfaces that the Infrastructure layer implements (`IApplicationDbContext`, `IEmailService`, `IStripeService`, `INotificationService`, etc.).

**What it contains:** One folder per feature (`Auth/`, `Tenants/`, `Billing/`, `Notifications/`, `Admin/`). Each feature folder has subfolders for commands and queries. MediatR pipeline behaviours for logging and validation.

**What it cannot reference:** Entity Framework Core directly (only through `IApplicationDbContext`), ASP.NET Core, Stripe SDK, Resend SDK. The Application layer defines what it needs through interfaces; Infrastructure provides the implementations.

### Acme.Infrastructure

Implements the interfaces defined in Application. This is where EF Core, Redis, Stripe, Resend, and Hangfire live.

**What it contains:** `ApplicationDbContext` with entity configurations and global query filters, `StripeService`, `ResendEmailService`, `RedisCache`, Hangfire job implementations, `TenantContext` scoped service, EF Core migrations.

**What it cannot reference:** Acme.Api directly. Infrastructure knows nothing about HTTP or controllers.

### Acme.Api

The host project. Contains controllers, middleware, program startup, and the dependency injection wiring that connects all layers.

**What it contains:** Controllers (thin — they delegate to MediatR immediately), `TenantResolutionMiddleware`, `SubscriptionMiddleware`, `HasPermissionAttribute` and the dynamic policy provider, Swagger configuration, CORS policy, program startup.

**What it cannot reference:** Entity Framework Core directly (only through the Application layer), domain logic. Controllers should contain no business logic.

## Clean Architecture dependency rule

The layers depend strictly inward. Nothing in an inner layer knows anything about an outer layer.

```
┌─────────────────────────────────────┐
│              Acme.Api               │  ← HTTP, middleware, DI wiring
├─────────────────────────────────────┤
│          Acme.Infrastructure        │  ← EF Core, Redis, Stripe, Resend
├─────────────────────────────────────┤
│          Acme.Application           │  ← Commands, queries, handlers, interfaces
├─────────────────────────────────────┤
│            Acme.Domain              │  ← Entities, enums, constants
└─────────────────────────────────────┘

Dependency direction: inward only →→→
Api references Application and Infrastructure.
Infrastructure references Application.
Application references Domain.
Domain references nothing in this solution.
```

Infrastructure is special: it references Application (to implement its interfaces) but Application does not reference Infrastructure. This is the Dependency Inversion Principle — Application defines the `IApplicationDbContext` interface, Infrastructure provides `ApplicationDbContext` that implements it.

## Frontend structure

```
frontend/src/
├── features/
│   ├── auth/          # Login, register, forgot password, magic link, OAuth
│   ├── tenants/       # Members, settings, invitations, roles
│   ├── billing/       # Plans, checkout, billing portal
│   ├── notifications/ # Bell icon, notification list, polling hook
│   ├── admin/         # Admin dashboard, user/tenant management, impersonation
│   └── profile/       # Display name, email change, password, account deletion
├── components/
│   ├── ui/            # shadcn/ui component wrappers
│   ├── layout/        # Sidebar, TopBar, PageWrapper
│   ├── command-palette/ # Cmd+K command palette
│   └── theme/         # ThemeProvider, ThemeToggle
├── hooks/
│   ├── useAuth.ts     # Zustand auth store accessor
│   ├── usePermissions.ts
│   ├── useTenant.ts
│   └── ...
├── lib/
│   ├── axios.ts       # Axios instance with JWT refresh interceptor
│   ├── queryClient.ts # TanStack Query client configuration
│   ├── constants.ts   # API base URL, plan names, permission strings
│   └── utils.ts       # cn() and other shared helpers
└── types/
    ├── auth.ts
    ├── tenant.ts
    ├── billing.ts
    └── ...
```

**Feature-based organization** means everything related to a feature lives together: the TypeScript types, the API calls, the TanStack Query hooks, and the page components. `features/billing/` contains the billing page, the billing hooks, billing types, and the billing API functions. You do not have to hunt across multiple top-level folders when working on a single feature.