Smart Tasks

Smart Tasks is a full-stack task-management application for teams. It is a modular monolith: a .NET 10 API owns the domain, persistence, authentication, authorization, and AI integration; an Angular 21 application provides the user interface.

The project is designed around Clean/Onion Architecture, explicit command/query handling, and safe operational defaults such as optimistic concurrency, soft deletion, refresh-token rotation, rate limiting, and a transactional outbox.

What the application does

• Registers, authenticates, refreshes, and signs out users.
• Supports Admin, ProjectManager, and TeamMember roles.
• Lets authorized users create projects, manage membership, and create and manage tasks.
• Provides project and task search, filtering, sorting, pagination, and dashboard summaries.
• Lets users change task status and assignments according to their role and project relationship.
• Produces a suggested task-description improvement through a configured AI provider. Suggestions are returned for review; they are never saved automatically.

Technology at a glance

Repository map

src/
  SmartTasks.Domain/          Business aggregates, value rules, domain events; no framework packages
  SmartTasks.Application/     Commands, queries, validation, use cases, ports, authorization rules
  SmartTasks.Infrastructure/  EF Core, Identity, repositories, AI clients, outbox/inbox implementations
  SmartTasks.Api/             Minimal API endpoints, middleware, configuration, composition root
tests/
  SmartTasks.*.Tests/         Domain, application, architecture, and infrastructure integration tests
web/smarttasks-web/           Angular application
docs/                         Architecture, requirements and implementation plans 

The root solution file is SmartTasks.slnx. The Angular application is intentionally a separate Node workspace in web/smarttasks-web.

Architecture and request flow

Dependency direction is strict:

Domain -> Application -> Infrastructure -> API

The architecture test project enforces these boundaries. The important responsibilities are:

For a write request, the normal path is:

HTTP endpoint -> command dispatcher -> validation -> application handler
-> aggregate/business rules -> EF Core unit of work
-> audit + domain-event-to-outbox interceptors -> SQL Server transaction

Reads use no-tracking projections through IReadModelService. Data access is authorized before filtering, counting, or paging.

Prerequisites

Install the following before running the project:

• .NET SDK 10

• SQL Server or SQL Server LocalDB

• Node.js compatible with npm 11.9.0 (the frontend declares this version)

• The EF Core CLI, if you will create or apply migrations:

  dotnet tool install --global dotnet-ef
  

Quick start

These steps start the API and web application locally.

1. Configure local settings

The API requires ConnectionStrings:DefaultConnection. Set it outside source control. In PowerShell, for the current terminal session:

$env:ConnectionStrings__DefaultConnection = 'Server=localhost;Database=SmartTasks;Trusted_Connection=True;TrustServerCertificate=True'
$env:Jwt__Issuer = 'SmartTasks.Api'
$env:Jwt__Audience = 'SmartTasks.Web'
$env:Jwt__SigningKey = '<a-random-secret-at-least-32-characters-long>'

For a development administrator, also set:

$env:AdminSeed__Enabled = 'true'
$env:AdminSeed__Email = 'admin@example.test'
$env:AdminSeed__Password = '<a-strong-development-password>'
$env:AdminSeed__DisplayName = 'Development Administrator'

Environment-variable names use double underscores in place of configuration colons. Do not commit connection strings, JWT signing keys, API keys, or admin passwords. See Configuration for the complete list.

2. Restore and create the database

From the repository root:

dotnet restore
dotnet ef database update --project src/SmartTasks.Infrastructure --startup-project src/SmartTasks.Api

The repository contains the initial SQL Server migration. The API deliberately does not apply migrations on startup.

3. Start the API

dotnet run --project src/SmartTasks.Api --launch-profile https

The default project profile serves the API at https://localhost:7019 (and http://localhost:5186). In Development, OpenAPI is available at https://localhost:7019/openapi/v1.json and Swagger UI is available at https://localhost:7019/swagger.

If HTTPS is not trusted on your workstation, run dotnet dev-certs https --trust and restart the API.

4. Start the Angular application

In a second terminal:

Set-Location web/smarttasks-web
npm ci
npm start

Open http://localhost:4200.

The development server uses proxy.conf.json for /api calls. Its checked-in target is the IIS Express HTTPS port (https://localhost:44305). If you use the dotnet run --launch-profile https command above, change the local proxy target to https://localhost:7019, or run the API through its IIS Express profile. Keep this a local environment choice; the frontend sends API requests to /api/v1.

Configuration

Configuration follows standard ASP.NET Core precedence. Use environment variables, your secret store, or an untracked local settings file in your environment; never place real secrets in committed JSON.

The development admin seed creates a user only when one with the configured email does not exist. It ensures that user has the Admin role, but does not reset an existing password.

AI configuration example

Select a provider and supply only its credentials through your secret store:

$env:AI__Provider = 'HuggingFace'
$env:AI__HuggingFace__BaseUrl = '<provider-base-url>'
$env:AI__HuggingFace__ApiKey = '<provider-api-key>'
$env:AI__HuggingFace__Model = '<model-id>'
$env:AI__HuggingFace__TimeoutSeconds = '20'

An unsupported provider or an unavailable AI service returns an ai.* error through the API. It does not save a changed task description.

Database and migrations

EF Core uses SQL Server and ApplicationDbContext combines Identity tables with the application tables:

• Projects, project members, and tasks
• Refresh tokens
• Transactional outbox messages

The model uses soft deletion for projects and tasks and RowVersion values for optimistic concurrency. A project deletion also soft-deletes its tasks.

Useful commands from the repository root:

# Apply existing migrations
dotnet ef database update --project src/SmartTasks.Infrastructure --startup-project src/SmartTasks.Api

# Create a migration after a deliberate model change
dotnet ef migrations add <DescriptiveName> --project src/SmartTasks.Infrastructure --startup-project src/SmartTasks.Api

# Generate a deployment-friendly idempotent script
dotnet ef migrations script --idempotent --project src/SmartTasks.Infrastructure --startup-project src/SmartTasks.Api --output artifacts/migrations.sql

Review generated migrations and deployment scripts before applying them to shared or production databases.

Authentication, authorization, and security

Authentication

• API clients authenticate with a JWT access token in Authorization: Bearer <token>.
• Access tokens are short-lived; refresh tokens use hashed persistence and family rotation. Reuse revokes the token family.
• The API sets a refresh-token cookie scoped to /api/v1/auth, with HttpOnly, Secure, and SameSite=Strict settings.
• Registration and login return a session response and set the refresh cookie. The server's refresh/logout handlers read the cookie; they do not take a refresh token from the JSON request body.
• Refresh and logout require an antiforgery token. First call GET /api/v1/auth/antiforgery-token, then send the value in X-XSRF-TOKEN for those requests.

Authorization

The role matrix is only the first check. Resource ownership, membership, and assignment checks add the final scope. For the detailed policy, see docs/role-permission-matrix.md.

Operational safeguards

• CORS only permits configured origins and credentials.
• API, authentication, and AI endpoints have separate fixed-window, per-IP limits. Rejections use HTTP 429 and include Retry-After.
• The global exception handler maps optimistic-concurrency conflicts to HTTP 409.
• Domain events are stored atomically with state changes in the outbox. The worker polls every five seconds, retries failures with exponential backoff, and dead-letters after five failures.
• Inbox records support future idempotent message consumers.

API guide

All application endpoints are rooted at /api/v1; JSON enum values are serialized as strings. Protected endpoints require a Bearer access token.

For exact schemas, validation details, status codes, and live authorization support, use Swagger UI in Development. Updates, member changes, and deletes require the current RowVersion in the request body. List endpoints accept query, pageNumber, pageSize, sortBy, and descending; task lists also accept status, priority, and assigneeId. Page sizes must be between 1 and 100.

Frontend guide

The Angular app uses standalone components and lazy-loaded feature routes. The main folders are:

web/smarttasks-web/src/app/
  core/       Authentication state, HTTP interceptors, route guards, application layout
  features/   Auth, projects, tasks, dashboard, and administration screens
  shared/     API types, enums, and reusable models

Feature route files export *_ROUTES. Keep API access in feature/core services rather than components, and keep styles component-scoped where practical. The UI uses ng-zorro-antd and SCSS.

Frontend commands:

Set-Location web/smarttasks-web
npm ci
npm start                 # Development server at http://localhost:4200
npm run build             # Production build to dist/smarttasks-web
npm test -- --watch=false # One test run
npx prettier --check "src/**/*.{ts,html,scss}" "*.json" ".vscode/*.json"

Development workflow

Build, test, and format

From the repository root:

dotnet build
dotnet test
dotnet format --verify-no-changes

From web/smarttasks-web:

npm run build
npm test -- --watch=false
npx prettier --write "src/**/*.{ts,html,scss}" "*.json" ".vscode/*.json"

The backend treats compiler/analyzer warnings as errors. Before opening a pull request, run the applicable commands above and inspect git diff --check for whitespace errors.

Adding backend behavior

1. Put invariant-enforcing behavior in the appropriate domain aggregate.
2. Add a command/query and handler in Application, plus validation if it accepts input.
3. Depend on an Application abstraction rather than Infrastructure directly.
4. Implement persistence or external integration in Infrastructure and register it through the existing DI extension.
5. Map the API endpoint in src/SmartTasks.Api/Endpoints without changing established contracts unintentionally.
6. Add tests at the narrowest useful layer and run the architecture tests.

Adding frontend behavior

1. Add the feature under web/smarttasks-web/src/app/features.
2. Expose its lazy routes through the feature route file.
3. Put remote calls in a typed service and UI state/presentation logic in components.
4. Use the shared models for API contracts and preserve error handling/interceptor behavior.
5. Format with Prettier and build/test the web application.

Project conventions and domain rules

• Commands mutate aggregates; queries are side-effect-free projections.
• Do not expose persistence entities through public contracts unless the architecture deliberately calls for it.
• Do not hard-code secrets, environment URLs, or connection strings.
• Do not delete or change public routes, DTO properties, enum values, configuration keys, or response/status-code behavior without checking consumers.
• Do not use blocking async calls (.Result, .Wait()) or wrap normal I/O in Task.Run.
• Preserve audit values, token hashes, concurrency values, and outbox/inbox state as server-owned data.
• Keep AI output as a user-reviewed suggestion.

The AI prompt contract is documented in PROMPTS.md.

Troubleshooting

Further reading

• Swagger Export
• Migration Script
• Role permission matrix
• Architecture and delivery plan
• Detailed implementation guide