Clean Architecture & Project Structures — C#, Dart (Flutter) & TypeScript

┌─────────────────────────────────────────────────────────────┐
│                     PRESENTATION                            │
│  (Controllers, Widgets, CLI, gRPC handlers)                 │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐    │
│  │                 INFRASTRUCTURE                      │    │
│  │  (Database, External APIs, File I/O, Cache)         │    │
│  │                                                     │    │
│  │  ┌─────────────────────────────────────────────┐    │    │
│  │  │              APPLICATION                    │    │    │
│  │  │  (Use Cases, DTOs, Validators)              │    │    │
│  │  │                                             │    │    │
│  │  │  ┌─────────────────────────────────────┐    │    │    │
│  │  │  │            DOMAIN                   │    │    │    │
│  │  │  │  (Entities, Interfaces, Services)   │    │    │    │
│  │  │  └─────────────────────────────────────┘    │    │    │
│  │  └─────────────────────────────────────────────┘    │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

Arrows point INWARD. Outer layers depend on inner layers. Never the reverse.

Solution_Name/
└── Project_Name.API/
    ├── Controllers/         # Handles HTTP requests AND business logic
    ├── Models/              # Database entities mixed with DTOs
    ├── Services/            # Business logic and database calls mixed
    ├── appsettings.json     # Configuration
    └── Program.cs           # Entry point and dependency injection

EnterpriseSolution/
│
├── src/
│   ├── Project.Domain/                    # Layer 1: Core (innermost)
│   │   ├── Entities/
│   │   │   ├── Driver.cs                  # Identity-based domain object
│   │   │   ├── Ride.cs
│   │   │   └── Vehicle.cs
│   │   ├── Enums/
│   │   │   ├── RideStatus.cs              # Requested, InProgress, Completed, Cancelled
│   │   │   └── VehicleType.cs
│   │   ├── Exceptions/
│   │   │   ├── DomainException.cs         # Base domain exception
│   │   │   └── RideAlreadyAcceptedException.cs
│   │   ├── Interfaces/
│   │   │   ├── IRideRepository.cs         # Data access contract
│   │   │   ├── IDriverRepository.cs
│   │   │   └── INotificationService.cs    # External capability contract
│   │   └── Services/
│   │       └── FareCalculationService.cs  # Pure business logic (no dependencies)
│   │
│   ├── Project.Application/               # Layer 2: References Domain ONLY
│   │   ├── DTOs/
│   │   │   ├── RequestRideDto.cs
│   │   │   └── RideResponseDto.cs
│   │   ├── Interfaces/
│   │   │   └── IRideApplicationService.cs
│   │   ├── Mappings/
│   │   │   └── RideMappingProfile.cs      # AutoMapper or manual mapping
│   │   ├── UseCases/                      # Or Commands/Queries (CQRS)
│   │   │   ├── RequestRideUseCase.cs
│   │   │   ├── AcceptRideUseCase.cs
│   │   │   └── CompleteRideUseCase.cs
│   │   └── Validators/
│   │       └── RequestRideValidator.cs    # FluentValidation rules
│   │
│   ├── Project.Infrastructure/            # Layer 3: References Application & Domain
│   │   ├── Data/
│   │   │   ├── AppDbContext.cs            # EF Core DbContext
│   │   │   ├── Configurations/
│   │   │   │   └── RideConfiguration.cs   # Fluent API entity config
│   │   │   └── Migrations/
│   │   ├── Repositories/
│   │   │   ├── RideRepository.cs          # Implements IRideRepository
│   │   │   └── DriverRepository.cs
│   │   ├── Services/
│   │   │   ├── PushNotificationService.cs # Implements INotificationService
│   │   │   └── StripePaymentService.cs
│   │   └── DependencyInjection.cs         # Extension method: services.AddInfrastructure()
│   │
│   └── Project.Api/                       # Layer 4: References Application & Infrastructure
│       ├── Controllers/
│       │   └── RidesController.cs         # Thin: parse HTTP → call UseCase → return DTO
│       ├── Middlewares/
│       │   ├── ExceptionHandlingMiddleware.cs
│       │   └── JwtAuthMiddleware.cs
│       ├── Filters/
│       │   └── ValidationFilter.cs
│       ├── appsettings.json
│       └── Program.cs                     # Wires DI container, middleware pipeline
│
├── tests/
│   ├── Project.Domain.Tests/
│   ├── Project.Application.Tests/
│   └── Project.Api.IntegrationTests/
│
└── EnterpriseSolution.sln

<!-- Project.Domain.csproj — ZERO project references -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>
</Project>

<!-- Project.Application.csproj — References Domain ONLY -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <ProjectReference Include="..\Project.Domain\Project.Domain.csproj" />
  </ItemGroup>
  <ItemGroup>
    <PackageReference Include="FluentValidation" Version="11.*" />
  </ItemGroup>
</Project>

<!-- Project.Infrastructure.csproj — References Application & Domain -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <ProjectReference Include="..\Project.Domain\Project.Domain.csproj" />
    <ProjectReference Include="..\Project.Application\Project.Application.csproj" />
  </ItemGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.EntityFrameworkCore" Version="8.*" />
    <PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="8.*" />
  </ItemGroup>
</Project>

<!-- Project.Api.csproj — References Application & Infrastructure -->
<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <ProjectReference Include="..\Project.Application\Project.Application.csproj" />
    <ProjectReference Include="..\Project.Infrastructure\Project.Infrastructure.csproj" />
  </ItemGroup>
</Project>

lib/
├── models/          # ALL data models in the app
├── screens/         # ALL UI pages
├── services/        # ALL network and database calls
├── widgets/         # ALL reusable UI components
└── main.dart

lib/
├── core/                           # App-wide shared utilities
│   ├── constants/
│   │   └── app_constants.dart
│   ├── errors/
│   │   ├── failures.dart           # Failure sealed class hierarchy
│   │   └── exceptions.dart         # Raw exception wrappers
│   ├── network/
│   │   ├── api_client.dart         # Configured Dio instance
│   │   └── interceptors.dart       # Auth token, retry logic
│   ├── theme/
│   │   └── app_theme.dart
│   └── usecases/
│       └── usecase.dart            # Abstract UseCase<Type, Params> base class
│
├── features/
│   ├── authentication/
│   │   ├── domain/
│   │   │   ├── entities/
│   │   │   │   └── user.dart       # Pure Dart class, no annotations
│   │   │   ├── repositories/
│   │   │   │   └── i_auth_repository.dart
│   │   │   └── usecases/
│   │   │       ├── login_user.dart
│   │   │       └── register_user.dart
│   │   ├── data/
│   │   │   ├── models/
│   │   │   │   └── user_model.dart # extends/maps to User entity + fromJson/toJson
│   │   │   ├── datasources/
│   │   │   │   ├── auth_remote_datasource.dart
│   │   │   │   └── auth_local_datasource.dart  # SharedPreferences/SQLite
│   │   │   └── repositories/
│   │   │       └── auth_repository_impl.dart   # Implements IAuthRepository
│   │   └── presentation/
│   │       ├── controllers/        # Riverpod StateNotifiers / Bloc
│   │       │   └── auth_controller.dart
│   │       ├── pages/
│   │       │   ├── login_page.dart
│   │       │   └── register_page.dart
│   │       └── widgets/
│   │           └── auth_form.dart
│   │
│   └── ride_tracking/
│       ├── domain/
│       │   ├── entities/
│       │   │   ├── ride.dart
│       │   │   └── location_point.dart
│       │   ├── repositories/
│       │   │   └── i_ride_repository.dart
│       │   └── usecases/
│       │       ├── request_ride.dart
│       │       └── track_active_ride.dart
│       ├── data/
│       │   ├── models/
│       │   │   └── ride_model.dart
│       │   ├── datasources/
│       │   │   ├── ride_remote_datasource.dart
│       │   │   └── ride_local_datasource.dart
│       │   └── repositories/
│       │       └── ride_repository_impl.dart
│       └── presentation/
│           ├── controllers/
│           │   └── ride_tracking_controller.dart
│           ├── pages/
│           │   └── active_ride_page.dart
│           └── widgets/
│               ├── map_overlay_widget.dart
│               └── driver_card.dart
│
├── injection_container.dart        # get_it / riverpod setup
└── main.dart                       # ProviderScope and routing

// injection_container.dart (using get_it)
import 'package:get_it/get_it.dart';

final sl = GetIt.instance;  // sl = service locator

Future<void> init() async {
  // Use Cases
  sl.registerLazySingleton(() => LoginUser(sl()));
  sl.registerLazySingleton(() => RegisterUser(sl()));

  // Repositories — interface mapped to implementation
  sl.registerLazySingleton<IAuthRepository>(
    () => AuthRepositoryImpl(
      remoteDatasource: sl(),
      localDatasource: sl(),
    ),
  );

  // Data Sources
  sl.registerLazySingleton<AuthRemoteDatasource>(
    () => AuthRemoteDatasourceImpl(client: sl()),
  );

  // External
  sl.registerLazySingleton(() => Dio());
}

src/
├── controllers/     # Req/Res handlers and business logic
├── models/          # Mongoose or TypeORM schemas
├── routes/          # Express router definitions
├── utils/           # Helper functions
└── index.ts         # Server setup

src/
├── domain/                          # Enterprise business rules
│   ├── entities/
│   │   ├── User.ts                  # Plain class with business invariants
│   │   └── Session.ts
│   ├── enums/
│   │   └── UserRole.ts
│   ├── interfaces/
│   │   ├── IUserRepository.ts       # Data access contract
│   │   ├── ISessionRepository.ts
│   │   └── IEmailService.ts         # External capability contract
│   └── services/
│       └── PasswordPolicyService.ts # Pure business logic
│
├── application/                     # Application business rules
│   ├── use-cases/
│   │   ├── RegisterUserUseCase.ts
│   │   ├── AuthenticateUserUseCase.ts
│   │   └── GetUserProfileUseCase.ts
│   ├── dtos/
│   │   ├── RegisterUserRequestDto.ts
│   │   └── UserResponseDto.ts
│   └── validators/
│       └── RegisterUserValidator.ts
│
├── infrastructure/                  # Frameworks and drivers
│   ├── database/
│   │   ├── PostgresConnection.ts
│   │   └── migrations/
│   ├── repositories/
│   │   ├── UserRepositoryImpl.ts    # Implements IUserRepository
│   │   └── SessionRepositoryImpl.ts
│   ├── services/
│   │   ├── SendGridEmailService.ts  # Implements IEmailService
│   │   ├── JwtAuthService.ts
│   │   └── RedisCacheService.ts
│   └── config/
│       └── env.ts                   # Environment variable parsing
│
├── presentation/                    # Interface adapters (delivery mechanism)
│   ├── http/
│   │   ├── controllers/
│   │   │   └── UserController.ts    # Parses HTTP, calls UseCase, returns DTO
│   │   ├── middlewares/
│   │   │   ├── AuthMiddleware.ts
│   │   │   └── ErrorHandlerMiddleware.ts
│   │   └── routes/
│   │       └── userRoutes.ts
│   └── Server.ts                    # Express/Fastify instantiation
│
├── container.ts                     # DI wiring (tsyringe, inversify, or manual)
└── main.ts                          # Application bootstrap

// main.ts — Composition Root
import { UserController } from './presentation/http/controllers/UserController';
import { RegisterUserUseCase } from './application/use-cases/RegisterUserUseCase';
import { UserRepositoryImpl } from './infrastructure/repositories/UserRepositoryImpl';
import { SendGridEmailService } from './infrastructure/services/SendGridEmailService';
import { PostgresConnection } from './infrastructure/database/PostgresConnection';

const db = new PostgresConnection();
const userRepository = new UserRepositoryImpl(db);
const emailService = new SendGridEmailService();
const registerUser = new RegisterUserUseCase(userRepository, emailService);
const userController = new UserController(registerUser);

// Wire into Express
app.post('/api/users', (req, res) => userController.register(req, res));

import { container } from 'tsyringe';
import { IUserRepository } from './domain/interfaces/IUserRepository';
import { UserRepositoryImpl } from './infrastructure/repositories/UserRepositoryImpl';

container.register<IUserRepository>('IUserRepository', { useClass: UserRepositoryImpl });

// In RegisterUserUseCase.ts
@injectable()
export class RegisterUserUseCase {
  constructor(
    @inject('IUserRepository') private userRepo: IUserRepository,
    @inject('IEmailService') private emailService: IEmailService,
  ) {}
}

Client (HTTP POST /api/users)
    │
    ▼
┌──────────────────────────────────────────┐
│ PRESENTATION: UserController.register()  │
│  1. Parse request body into DTO          │
│  2. Call RegisterUserUseCase.execute()    │
│  3. Return formatted HTTP response       │
└──────────────┬───────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────┐
│ APPLICATION: RegisterUserUseCase         │
│  1. Validate DTO (RegisterUserValidator) │
│  2. Check IUserRepository.existsByEmail()│
│  3. Hash password (IHashService)         │
│  4. Create User entity                   │
│  5. Call IUserRepository.save(user)      │
│  6. Call IEmailService.sendWelcome()     │
│  7. Map User entity → UserResponseDto    │
│  8. Return UserResponseDto               │
└──────────────┬───────────────────────────┘
               │ (calls interfaces)
               ▼
┌──────────────────────────────────────────┐
│ INFRASTRUCTURE: UserRepositoryImpl       │
│  1. Map User entity → UserModel (ORM)    │
│  2. INSERT INTO users ... (PostgreSQL)   │
│  3. Map result back to User entity       │
│  4. Return User entity                   │
│                                          │
│ INFRASTRUCTURE: SendGridEmailService     │
│  1. Build email template                 │
│  2. Call SendGrid API                    │
└──────────────────────────────────────────┘

// domain/entities/User.ts
export class User {
  constructor(
    public readonly id: string,
    public readonly email: string,
    public readonly hashedPassword: string,
    public readonly createdAt: Date,
  ) {}
}

// domain/interfaces/IUserRepository.ts
import { User } from '../entities/User';

export interface IUserRepository {
  existsByEmail(email: string): Promise<boolean>;
  save(user: User): Promise<User>;
  findById(id: string): Promise<User | null>;
}

// application/use-cases/RegisterUserUseCase.ts
import { User } from '../../domain/entities/User';
import { IUserRepository } from '../../domain/interfaces/IUserRepository';
import { IEmailService } from '../../domain/interfaces/IEmailService';
import { IHashService } from '../../domain/interfaces/IHashService';
import { RegisterUserRequestDto } from '../dtos/RegisterUserRequestDto';
import { UserResponseDto } from '../dtos/UserResponseDto';
import { v4 as uuidv4 } from 'uuid';

export class RegisterUserUseCase {
  constructor(
    private userRepo: IUserRepository,
    private emailService: IEmailService,
    private hashService: IHashService,
  ) {}

  async execute(dto: RegisterUserRequestDto): Promise<UserResponseDto> {
    // 1. Check uniqueness
    const exists = await this.userRepo.existsByEmail(dto.email);
    if (exists) {
      throw new Error('Email already registered');
    }

    // 2. Hash password
    const hashed = await this.hashService.hash(dto.password);

    // 3. Create domain entity
    const user = new User(uuidv4(), dto.email, hashed, new Date());

    // 4. Persist
    const saved = await this.userRepo.save(user);

    // 5. Side effect: send welcome email (fire-and-forget or awaited)
    await this.emailService.sendWelcome(saved.email);

    // 6. Map to response DTO
    return { id: saved.id, email: saved.email, createdAt: saved.createdAt.toISOString() };
  }
}

// infrastructure/repositories/UserRepositoryImpl.ts
import { IUserRepository } from '../../domain/interfaces/IUserRepository';
import { User } from '../../domain/entities/User';
import { Pool } from 'pg';

export class UserRepositoryImpl implements IUserRepository {
  constructor(private pool: Pool) {}

  async existsByEmail(email: string): Promise<boolean> {
    const result = await this.pool.query('SELECT 1 FROM users WHERE email = $1', [email]);
    return result.rowCount > 0;
  }

  async save(user: User): Promise<User> {
    await this.pool.query(
      'INSERT INTO users (id, email, hashed_password, created_at) VALUES ($1, $2, $3, $4)',
      [user.id, user.email, user.hashedPassword, user.createdAt],
    );
    return user;
  }

  async findById(id: string): Promise<User | null> {
    const result = await this.pool.query('SELECT * FROM users WHERE id = $1', [id]);
    if (result.rows.length === 0) return null;
    const row = result.rows[0];
    return new User(row.id, row.email, row.hashed_password, row.created_at);
  }
}

// presentation/http/controllers/UserController.ts
import { Request, Response } from 'express';
import { RegisterUserUseCase } from '../../../application/use-cases/RegisterUserUseCase';

export class UserController {
  constructor(private registerUser: RegisterUserUseCase) {}

  async register(req: Request, res: Response): Promise<void> {
    try {
      const dto = req.body; // In production, validate/parse with zod or class-validator
      const result = await this.registerUser.execute(dto);
      res.status(201).json(result);
    } catch (error: any) {
      if (error.message === 'Email already registered') {
        res.status(409).json({ error: error.message });
      } else {
        res.status(500).json({ error: 'Internal server error' });
      }
    }
  }
}