Skip to content

AGENTS.md

Latest commit

 

History

History
96 lines (70 loc) · 3.79 KB

AGENTS.md

File metadata and controls

96 lines (70 loc) · 3.79 KB
Raw

Order Transformer - Agent Instructions

Canonical Source

This file is the canonical repository instruction file for coding agents working in this repository. If similar guidance exists in CLAUDE.md or other tool-specific files, keep this file as the primary source of truth.

Project Overview

This is a .NET 10 web application that monitors Azure Blob Storage via the Azurite emulator for incoming XML order files, transforms them to JSON, and writes output back to blob storage. It includes a React UI for viewing processed orders and uploading new files.

Architecture

  • Pipeline flow: Parse XML -> Validate -> Map Fields -> Transform to JSON -> Store
  • Dependency injection: services are registered via interfaces in Program.cs
  • Background processing: BlobPollingWorker polls blob storage on a timer
  • Backend API: Minimal API endpoints list, view, upload, and track orders
  • Frontend UI: React single-page app served from wwwroot in production or the Vite dev server in development

Key Files

  • src/OrderTransformer/Worker/TransformationPipeline.cs - Orchestrates the processing pipeline
  • src/OrderTransformer/Worker/BlobPollingWorker.cs - Polls blob storage for new files
  • src/OrderTransformer/Models/OrderModels.cs - Domain models using immutable records
  • src/OrderTransformer/Services/ - Service interfaces and implementations
  • src/OrderTransformer/Api/OrderEndpoints.cs - Order browsing and upload endpoints
  • src/OrderTransformer/Api/StatusEndpoints.cs - Upload status endpoint stub
  • ui/ - React frontend application
  • specs/ - Feature specs, design docs, ADRs, and test plans

Candidate Extension Points

Backend

  • src/OrderTransformer/Services/OrderValidatorService.cs - Order validation rules
  • src/OrderTransformer/Services/FieldMappingService.cs - Display-value mapping
  • src/OrderTransformer/Api/StatusEndpoints.cs - Processing status endpoint
  • tests/OrderTransformer.Tests/Services/OrderValidatorServiceTests.cs - Validation tests
  • tests/OrderTransformer.Tests/Services/FieldMappingServiceTests.cs - Mapping tests

Frontend

  • ui/src/hooks/useProcessingStatus.ts - Polling hook for upload status
  • ui/src/components/ProcessingStatus.tsx - Status display component
  • ui/src/api/client.ts - getStatus() implementation

Specs Workflow

  • Treat specs/ as the source of truth for planned work
  • Read the relevant feature spec before implementing changes
  • Keep feature specs focused on business requirements and acceptance criteria
  • Put implementation structure, file touchpoints, and test strategy in matching design docs under specs/design/

Conventions

C# / .NET

  • Use records with init setters when matching existing models
  • Follow the existing interface plus implementation service pattern
  • Preserve the current namespace structure
  • Use xUnit with [Fact] and [Theory] for tests
  • Use System.Text.Json for serialization
  • Use System.Xml.Linq for XML parsing

TypeScript / React

  • Use TypeScript strict mode and avoid any
  • Define explicit API response types where needed
  • Use functional components with hooks
  • Use TailwindCSS for styling
  • Use React Router v7 for navigation
  • Route frontend API calls through ui/src/api/client.ts

Working Style

  • Prefer extending existing patterns over introducing new abstractions
  • Keep invalid-order handling non-fatal unless a spec explicitly changes that behavior
  • For feature work, preserve existing behavior outside the requested scope
  • Add or update tests when changing backend or frontend behavior

Commands

# .NET
dotnet build src/OrderTransformer
dotnet test tests/OrderTransformer.Tests
dotnet run --project src/OrderTransformer

# UI
cd ui && pnpm install
cd ui && pnpm dev
cd ui && pnpm build

# Docker
docker compose up -d
docker compose --profile app up --build -d