ResearchApps Documentation

For GitHub Copilot/AI Agents: This documentation is optimized for AI-assisted code generation. Start with the Quick Decision Tree below or jump to Module Generation Quick Start.

Quick Reference

Document	Purpose
Architecture Overview	System layers, data flow, project structure
Service Patterns	ServiceResponse, transactions, Mapperly
Database & Stored Procedures	SQL Server, Dapper, stored procedure conventions
Workflow System	PR/CO approval workflows, user-based authorization
Real-time Notifications	SignalR hubs, notification patterns
Testing Guide	xUnit, Moq, test patterns
Adding New Entities	Step-by-step CRUD implementation
Module Generation Quick Start	Fast-track guide for generating new modules
Coding Style Guide	Naming conventions, patterns, consistency rules
Multi-Tenancy Guide	Tenant architecture, admin, onboarding, developer guide

System Overview

ResearchApps is a Clean Architecture ASP.NET Core 10.0 application for:

• Purchase Requests (PR) - Multi-level workflow approvals
• Customer Orders (CO) - Order management with approval workflows
• Delivery Orders (DO) - Fulfillment tracking

Key Technologies

• ASP.NET Core 10.0 (MVC + REST API)
• SQL Server with Stored Procedures (Dapper, no EF queries)
• Mapperly (source-generated object mapping)
• SignalR (real-time notifications)
• Serilog (structured logging)
• xUnit + Moq (testing)

Quick Decision Tree for AI Agents

┌─────────────────────────────────────────────────────────────┐
│ What needs to be generated?                                 │
└─────────────────────────────────────────────────────────────┘
                        │
        ┌───────────────┼───────────────┐
        │               │               │
        ▼               ▼               ▼
  ┌─────────┐    ┌─────────┐    ┌──────────┐
  │ New     │    │ New     │    │ Workflow │
  │ Entity  │    │ Feature │    │ Action   │
  │ (CRUD)  │    │ Method  │    │          │
  └─────────┘    └─────────┘    └──────────┘
        │               │               │
        ▼               ▼               ▼
   See Guide        Add to         See Workflow
   07 + 08         Existing        Guide 04
                   Service

┌─────────────────────────────────────────────────────────────┐
│ Generation Order for New Entity (ALWAYS follow):            │
├─────────────────────────────────────────────────────────────┤
│ 1. Domain Entity        (ResearchApps.Domain)              │
│ 2. ViewModel           (ResearchApps.Service.Vm)           │
│ 3. Mapper Declarations (ResearchApps.Mapper)               │
│ 4. Repo Interface      (ResearchApps.Repo.Interface)       │
│ 5. Repo Implementation (ResearchApps.Repo)                 │
│ 6. Service Interface   (ResearchApps.Service.Interface)    │
│ 7. Service Impl        (ResearchApps.Service)              │
│ 8. API Controller      (ResearchApps.Web/Controllers/Api)  │
│ 9. Stored Procedures   (ResearchApps.Web/Context/Data/...)│
│ 10. Tests              (ResearchApps.Service.Tests)        │
│ 11. Constants          (ResearchApps.Common/Constants)     │
└─────────────────────────────────────────────────────────────┘

Critical Patterns for Module Generation

✅ Always Do

• Use ServiceResponse<T> (generic) for data-returning operations
• Call _dbTransaction.Commit() after INSERT/UPDATE/DELETE
• Instantiate MapperlyMapper as field: new MapperlyMapper()
• Set CreatedBy/ModifiedBy from _userClaimDto.Username
• All async methods must accept CancellationToken ct
• Use source-generated logging ([LoggerMessage])
• Register interfaces in ServiceCollectionExtensions.cs

❌ Never Do

• Use EF Core navigation properties or LINQ queries
• Manually create DbConnection or DbTransaction (always injected)
• Register MapperlyMapper in DI (it's instantiated directly)
• Use string interpolation in logging
• Forget transaction commit for mutations
• Use permission-based checks for workflow buttons (use username checks)

Module Generation Checklist

When generating a new complete CRUD entity:

- [ ] Domain entity created (flat, no nav properties)
- [ ] ViewModel with validation attributes
- [ ] Mapperly partial method declarations added
- [ ] Repository interface defined
- [ ] Repository implementation with Dapper
- [ ] Repository registered in ServiceCollectionExtensions
- [ ] Service interface defined
- [ ] Service implementation with logging
- [ ] Service registered in ServiceCollectionExtensions
- [ ] API controller with authorization
- [ ] Permission constants added
- [ ] 5 core stored procedures (Insert, Select, SelectById, Update, Delete)
- [ ] Unit tests for all public methods