jdescopingtool/AGENTS.md

# AGENTS.md

This file provides guidance to coding agents working in this repository.

## Project Overview

This is a **migration project** to convert a legacy .NET Framework 4.8 application
("LotFinder" / JDE Scoping Tool) to .NET 10.

### Folder Structure
```
JdeScopingTool/
├── OLD/            # Legacy .NET Framework 4.8 source code (read-only reference)
├── NEW/            # New .NET 10 solution (build here)
├── SPECS/          # OpenSpec specifications and design documents
├── PLANS/          # Design plans, implementation plans, and task lists
└── DOCUMENTATION/  # Project documentation
```

### Legacy System Purpose
- Caches data from JDE (JD Edwards - Oracle) and CMS (Sybase) enterprise systems into SQL Server
- Allows users to create complex searches across work orders, lots, items, operators, and work centers
- Processes searches asynchronously and exports results to Excel
- Provides real-time status updates via SignalR

### Migration Target
- **Single .NET 10 service** (combines the legacy web app + worker service)
- **Blazor WebAssembly UI** (replaces ASP.NET MVC + Razor views)

## Legacy Architecture (OLD/)

### Solution Structure
```
OLD/LotFinder.sln
├── WebInterface/       # ASP.NET MVC 5 web application
├── WorkerService/      # Windows Service (Topshelf) - search processor + data refresher
├── DataModel/          # Shared library (Commons.csproj) - models, DB access, helpers
├── Database/           # SQL Server database project (.sqlproj)
└── TestApp/            # Console test application
```

### Key Components

**WebInterface** - ASP.NET MVC with SignalR
- Controllers: `SearchController` (main), `LookupController` (autocomplete APIs), `AccountController` (LDAP auth)
- SignalR Hub: `StatusHub` for real-time search status updates
- Uses Forms auth with LDAP backend

**WorkerService** - Background processor (Topshelf service)
- `WorkProcessor`: Main work loop - checks for pending data updates, then processes queued searches
- `UpdateProcessor`: Syncs data from JDE/CMS to local SQL Server cache (mass/daily/hourly schedules)
- `ExcelWriter`: Generates Excel output using EPPlus
- Data source configs in `dsconfig/*.json` files

**DataModel (Commons)** - Shared library
- `Process/LotFinderDB*.cs`: SQL Server cache database access (Dapper)
- `Process/JDE*.cs`: Oracle JDE queries
- `Process/CMS*.cs`: Sybase CMS queries
- `Models/`: Domain models (WorkOrder, Lot, Item, Search, etc.)
- `ViewModels/`: DTOs for API responses
- `Config.cs`: Connection strings (encrypted passwords)

### Data Flow
1. User submits search via web UI -> stored in `Search` table with status=Queued
2. WorkerService polls for queued searches
3. Service executes search against local cache, generates Excel
4. Results stored in `Search.Results` (VARBINARY), status updated
5. SignalR pushes status updates to connected clients

### Key Database Tables
- `Search`: User search requests and results
- `DataUpdate`: Tracks cache refresh timestamps per table
- `WorkOrder_Curr/Hist`, `LotUsage_Curr/Hist`, etc.: Cached JDE data (current + historical)
- `Lot`, `Item`, `ProfitCenter`, `WorkCenter`, `JdeUser`: Reference data

### External Dependencies
- **DDTek.Oracle**: Progress DataDirect Oracle driver
- **Sybase.AdoNet4.AseClient**: Sybase database driver
- **Dapper**: Micro-ORM for SQL queries
- **EPPlus**: Excel generation
- **Topshelf**: Windows service hosting
- **SignalR**: Real-time web communication

## Migration Considerations

### What to Preserve
- Search criteria model (`SearchCriteria`, `SearchCriteriaViewModel`)
- JDE/CMS query logic (files in `DataModel/Process/JDE*.cs`, `CMS*.cs`)
- Excel generation logic (`WorkerService/Process/ExcelWriter.cs`)
- Data sync scheduling patterns (mass/daily/hourly from dsconfig)
- Query templates (`WorkerService/Templates/QueryTemplate.cs`)

### What Changes
- Topshelf -> .NET hosted service with BackgroundService
- SignalR (legacy) -> modern ASP.NET Core SignalR
- ASP.NET MVC -> Blazor WebAssembly
- Forms auth -> ASP.NET Core Identity with LDAP
- `System.Data.SqlClient` -> `Microsoft.Data.SqlClient`

### Authentication Pattern
Legacy uses LDAP authentication with group membership check. Config values:
- `LDAPUrl`: Directory server URL(s)
- `LDAPGroup`: Required group membership

## OpenSpec Workflow

This project uses OpenSpec for change management. See `.claude/commands/openspec/`
for proposal, apply, and archive workflows. Key principles:
- Favor minimal implementations
- Keep changes tightly scoped
- Create design docs before implementation

## Documentation Guidelines

When writing or updating documentation, consult the `DOCUMENTATION/Instructions/` folder:
- `DOCUMENTATION/Instructions/GeneratingDocs.md` - How to create new documentation
- `DOCUMENTATION/Instructions/UpdatingDocs.md` - When and how to update existing docs
- `DOCUMENTATION/Instructions/StyleGuide.md` - Writing conventions and formatting rules
- `DOCUMENTATION/Instructions/ComponentMap.md` - Maps source code to documentation folders

Key principles:
- Read source code before documenting
- Use code snippets from actual codebase (never invent examples)
- Follow the component mapping for file organization
- Update documentation when code changes

## Plans and Task Lists

Store design plans, implementation plans, and task list files in the `PLANS/` folder:
- **Design plans** - Architecture decisions, component designs
- **Implementation plans** - Step-by-step implementation guides
- **Task lists** - Tracked work items and checklists

This keeps planning artifacts organized and separate from specifications (SPECS/)
and documentation (DOCUMENTATION/).

## Local Development Database

The `db_info.md` file contains connection information for the local SQL Server
development database:

- Docker container details (`scopingtool-sqlserver` on port 1434)
- SA credentials (admin access)
- Application credentials (`scopingapp` user with read/write/execute/truncate permissions)
- Connection strings for .NET configuration

Note: This file contains plain-text credentials for local development only. Do
not commit to source control or use in production.

## Sync Checklist

When `CLAUDE.md` changes, review `AGENTS.md` and update any modified sections so
both files stay aligned.