Initial commit: JDE Scoping Tool migration project

Set up repository with legacy .NET Framework 4.8 source (OLD/), new .NET 10 Blazor solution (NEW/), OpenSpec specifications, documentation, and project configuration.
2026-01-02 07:43:29 -05:00
commit 26ff8d9b4f
1761 changed files with 596509 additions and 0 deletions
@@ -0,0 +1,282 @@
+# Documentation Style Guide
+
+This guide defines writing conventions and formatting rules for all JDE Scoping Tool documentation.
+
+## Tone and Voice
+
+### Be Technical and Direct
+
+Write for developers who are familiar with .NET. Don't explain basic concepts like dependency injection or async/await unless they're used in an unusual way.
+
+**Good:**
+> The `SearchProcessor` executes queued searches against the local cache and generates Excel results.
+
+**Avoid:**
+> The SearchProcessor is a really powerful component that helps manage all your searches efficiently!
+
+### Explain "Why" Not Just "What"
+
+Document the reasoning behind patterns and decisions, not just the mechanics.
+
+**Good:**
+> Data sync uses a retry pattern with exponential backoff because JDE connections can be temporarily unavailable during peak ERP usage.
+
+**Avoid:**
+> Data sync uses retry with backoff.
+
+### Use Present Tense
+
+Describe what the code does, not what it will do.
+
+**Good:**
+> The actor validates the message before processing.
+
+**Avoid:**
+> The actor will validate the message before processing.
+
+### No Marketing Language
+
+This is internal technical documentation. Avoid superlatives and promotional language.
+
+**Avoid:** "powerful", "robust", "cutting-edge", "seamless", "blazing fast"
+
+## Formatting Rules
+
+### File Names
+
+Use `PascalCase.md` for all documentation files:
+- `Overview.md`
+- `HealthChecks.md`
+- `StateMachines.md`
+- `SignalR.md`
+
+### Headings
+
+- **H1 (`#`):** Document title only, Title Case
+- **H2 (`##`):** Major sections, Title Case
+- **H3 (`###`):** Subsections, Sentence case
+- **H4+ (`####`):** Rarely needed, Sentence case
+
+```markdown
+# Actor Health Checks
+
+## Configuration Options
+
+### Setting the timeout
+
+#### Default values
+```
+
+### Code Blocks
+
+Always specify the language:
+
+````markdown
+```csharp
+public class MyActor : ReceiveActor { }
+```
+
+```json
+{
+  "Setting": "value"
+}
+```
+
+```bash
+dotnet build
+```
+````
+
+Supported languages: `csharp`, `json`, `bash`, `xml`, `sql`, `yaml`, `html`, `css`, `javascript`
+
+### Code Snippets
+
+**Length:** 5-25 lines is typical. Shorter for simple concepts, longer for complete examples.
+
+**Context:** Include enough to understand where the code lives:
+
+```csharp
+// Good - shows class context
+public class SearchProcessor : BackgroundService
+{
+    public SearchProcessor(ISearchRepository repository)
+    {
+        _repository = repository;
+    }
+}
+
+// Avoid - orphaned snippet
+_repository = repository;
+```
+
+**Accuracy:** Only use code that exists in the codebase. Never invent examples.
+
+### Lists
+
+Use bullet points for unordered items:
+```markdown
+- First item
+- Second item
+- Third item
+```
+
+Use numbers for sequential steps:
+```markdown
+1. Do this first
+2. Then do this
+3. Finally do this
+```
+
+### Tables
+
+Use tables for structured reference information:
+
+```markdown
+| Option | Default | Description |
+|--------|---------|-------------|
+| `Timeout` | `5000` | Milliseconds to wait |
+| `RetryCount` | `3` | Number of retry attempts |
+```
+
+### Inline Code
+
+Use backticks for:
+- Class names: `SearchProcessor`
+- Method names: `ProcessQueuedSearches()`
+- File names: `appsettings.json`
+- Configuration keys: `JdeScoping:ConnectionStrings`
+- Command-line commands: `dotnet build`
+
+### Links
+
+Use relative paths for internal documentation:
+```markdown
+[See the Search guide](../Search/Overview.md)
+[Configuration options](./Configuration.md)
+```
+
+Use descriptive link text:
+```markdown
+<!-- Good -->
+See the [Data Sync Configuration](../DataSync/Configuration.md) documentation.
+
+<!-- Avoid -->
+See [here](../DataSync/Configuration.md) for more.
+```
+
+## Structure Conventions
+
+### Document Opening
+
+Every document starts with:
+1. H1 title
+2. 1-2 sentence description of purpose
+
+```markdown
+# Search Processor
+
+The search processor handles queued searches, executing queries against the local cache and generating Excel results.
+```
+
+### Section Organization
+
+Organize content from general to specific:
+1. Overview/introduction
+2. Key concepts (if needed)
+3. Basic usage
+4. Advanced usage
+5. Configuration
+6. Troubleshooting
+7. Related documentation
+
+### Code Example Placement
+
+Place code examples immediately after the concept they illustrate:
+
+```markdown
+## Search Execution
+
+Searches are executed against the local cache using Dapper:
+
+```csharp
+var results = await connection.QueryAsync<WorkOrder>(query, parameters);
+```
+
+Each search returns a collection of matching records...
+```
+
+### Related Documentation Section
+
+End each document with links to related topics:
+
+```markdown
+## Related Documentation
+
+- [Search Criteria](./Criteria.md)
+- [Excel Export](../Export/Excel.md)
+- [Configuration](../Configuration/Search.md)
+```
+
+## Naming Conventions
+
+### Match Code Exactly
+
+Use the exact names from source code:
+- `SearchProcessor` not "Search Processor"
+- `WorkOrder` not "Work Order"
+- `ISearchRepository` not "search repository interface"
+
+### Acronyms
+
+Spell out on first use, then use acronym:
+> JD Edwards (JDE) is an Oracle ERP system. JDE stores work order and lot data...
+
+Common acronyms that don't need expansion:
+- API
+- JSON
+- SQL
+- HTTP/HTTPS
+- REST
+- JWT
+- UI
+
+### File Paths
+
+Use forward slashes and backticks:
+- `NEW/src/Services/SearchProcessor.cs`
+- `appsettings.json`
+- `DOCUMENTATION/Search/Overview.md`
+
+## What to Avoid
+
+### Don't Document the Obvious
+
+```markdown
+<!-- Avoid -->
+## Constructor
+
+The constructor creates a new instance of the class.
+
+<!-- Better - only document if there's something notable -->
+## Constructor
+
+The constructor accepts an `IActorRef` for the gateway actor, which must be resolved before actor creation.
+```
+
+### Don't Duplicate Source Code Comments
+
+If code has good comments, reference the file rather than copying:
+> See `SearchProcessor.cs` lines 45-60 for the search execution logic.
+
+### Don't Include Temporary Information
+
+Avoid dates, version numbers, or "coming soon" notes that will become stale.
+
+### Don't Over-Explain .NET Basics
+
+Assume readers know:
+- Dependency injection
+- async/await
+- LINQ
+- Entity Framework basics
+- ASP.NET Core middleware pipeline