# Module Implementation Roadmap

**Status**: Architecture extraction complete. Implementation pipeline ready.

**Last Updated**: After creating MODULE_ARCHITECTURE.md, SALES_MODULE_GUIDE.md, STANDARDIZATION_GUIDE.md, FOLDER_STRUCTURE_GUIDE.md

---

## Documentation Available

### Quick Start (Pick One Based on Your Role)

| Role | Read First | Then Read |
|------|------------|-----------|
| **New to Pattern** | MODULE_ARCHITECTURE.md | SALES_MODULE_GUIDE.md example |
| **Implementing Sales** | SALES_MODULE_GUIDE.md | Step 1-6 walkthrough with code |
| **Implementing Other Domains** | STANDARDIZATION_GUIDE.md | Domain-specific examples |
| **Setting Up Folder/Files** | FOLDER_STRUCTURE_GUIDE.md | Initialization checklist |
| **Decision: Create or Extend** | STANDARDIZATION_GUIDE.md | Decision tree |

### Document Reference Map

```
┌─ MODULE_ARCHITECTURE.md
│  ├─ Read if: Understanding the pattern architecture
│  ├─ Covers: 3-layer structure, 5 ports, service pattern, testing strategy
│  └─ Length: 400+ lines
│
├─ SALES_MODULE_GUIDE.md
│  ├─ Read if: Implementing a new domain module
│  ├─ Covers: Step-by-step implementation, complete code examples
│  └─ Length: 500+ lines (mostly code examples)
│
├─ STANDARDIZATION_GUIDE.md
│  ├─ Read if: Planning rollout or deciding what to customize
│  ├─ Covers: Reuse patterns, common pitfalls, examples for each domain
│  └─ Length: 400+ lines
│
├─ FOLDER_STRUCTURE_GUIDE.md
│  ├─ Read if: Setting up folder structure or naming files
│  ├─ Covers: Directory layout, naming conventions, file templates
│  └─ Length: 350+ lines
│
└─ purchases/ (Production Code)
   ├─ Read if: Need working examples of implemented pattern
   ├─ Use as: Reference implementation (proven, tested)
   └─ Note: This is the actual Purchases module (14 files, production-ready)
```

---

## Implementation Phases

### Phase 1: Sales Module (Recommended First)

**Effort**: 6-8 hours (first module following template)

**Resources**:
- SALES_MODULE_GUIDE.md: Complete step-by-step guide
- purchases/ folder: Reference implementation for patterns
- FOLDER_STRUCTURE_GUIDE.md: Naming conventions and file setup

**Scope**:
- Create domain types (SalesInvoiceCreateCommand, etc.)
- Implement pure domain functions (calculateSalesInvoiceTotals, validators)
- Define 5 ports + default adapters
- Build application service (5-port DI, orchestration)
- Implement JSON/Postgres repository adapters
- Write domain/contract/service tests

**Success Criteria**:
```bash
npm run test:sales  # ✅ 10+ tests passing
```

**Key Customizations** (vs Purchases):
- Entity: SalesInvoice instead of PurchaseOrder
- Direction: Outbound to customer (vs inbound from supplier)
- Actor: Sales rep (vs procurement officer)
- Inventory effect: Reduces stock (vs increases)
- GL posting: Debit AR, credit Revenue (vs Debit Inventory, credit AP)

**Estimated Timeline**: Complete by end of week

---

### Phase 2: Inventory Module (Complex Side Effects)

**Effort**: 8-10 hours (second module, more side effects)

**Resources**:
- STANDARDIZATION_GUIDE.md: Copy/paste safe patterns
- FOLDER_STRUCTURE_GUIDE.md: File structure & naming
- purchases/ + sales/: Two reference implementations

**Scope**:
- Stock movements tracking (receipt, issue, transfer, adjustment)
- Bin location management (multi-location warehouses)
- FIFO/Weighted-Avg costing calculation
- Low stock alerts (reorder points)
- Physical count reconciliation

**Complexity Increase**:
- More side effects (4-5 vs 3-4 in Sales/Purchases)
- Complex domain logic (costing methods, multi-warehouse)
- Repository queries (by warehouse, by item, by date range)

**Success Criteria**:
```bash
npm run test:inventory  # ✅ 15+ tests passing
npm run test:sales      # ✅ Still passing (inventory integration)
npm run test:purchases  # ✅ Still passing (inventory integration)
```

**Estimated Timeline**: 2 weeks after Sales complete

---

### Phase 3: Accounting Module (Read-Heavy, Balancing)

**Effort**: 10-12 hours (data-heavy, validation-heavy)

**Resources**:
- STANDARDIZATION_GUIDE.md: Accounting-specific example
- FOLDER_STRUCTURE_GUIDE.md: File structure
- purchases/ + sales/ + inventory/: Multiple references

**Scope**:
- Journal entry creation (already a legacy helper, needs wrapping as port)
- GL account validation (chart of accounts hierarchy)
- Period closing & period locking
- Trial balance calculations
- Intercompany elimination (if multi-company)

**Complexity Increase**:
- Mostly reads from other modules (Sales, Purchases, Inventory post to journals)
- Heavy validation (balancing, account rules, period rules)
- No side effects (accounting is a side effect target)
- Referential integrity (GL posting history is append-only)

**Success Criteria**:
```bash
npm run test:accounting  # ✅ 12+ tests passing
npm run test:sales       # ✅ Accounting port integration working
npm run test:purchases   # ✅ Accounting port integration working
npm run test:inventory   # ✅ Still passing
```

**Estimated Timeline**: 3-4 weeks after Inventory complete

---

### Phase 4: Payroll Module (Complex Domain, Scheduled)

**Effort**: 12-15 hours (most complex, scheduled execution)

**Resources**:
- STANDARDIZATION_GUIDE.md: Payroll-specific example
- All prior modules: Patterns proven

**Scope**:
- Employee master data (hire, termination, compensation changes)
- Payroll calculation (gross, deductions, withholdings)
- Tax withholding calculation (federal, state, local if applicable)
- Pay slip generation (PDF, email)
- Bank file generation (ACH, wire formats)
- GL posting (payroll expense, withholdings liability)
- Scheduled execution (monthly, biweekly cycles)

**Complexity Increase**:
- Most complex domain logic (tax withholding, benefits, deductions)
- Scheduled execution (monthly/biweekly batches, not real-time)
- Multiple outputs (pay slips, bank files, GL entries)
- Regulatory compliance (tax law changes)
- Multi-entity support (per-company payroll rules)

**Success Criteria**:
```bash
npm run test:payroll     # ✅ 15+ tests passing
npm run test:accounting  # ✅ Still passing (GL posting)
# All prior modules still passing
```

**Estimated Timeline**: 4-5 weeks after Accounting complete

---

## Quick Implementation Checklist

### Before Starting New Module

```markdown
## Pre-Implementation

- [ ] Read SALES_MODULE_GUIDE.md (or appropriate guide)
- [ ] Review purchases/ folder structure (or prior module)
- [ ] Pick entity name (e.g., SalesInvoice, InventoryMovement)
- [ ] Define ID prefix (e.g., 'si' for sales-invoice)
- [ ] List required ports (usually 5: Repository, Accounting, SideEffects, ReferenceData, IdGenerator)
- [ ] Identify legacy helpers to wrap (grep lib/actions.ts, lib/data.ts)
- [ ] Create feature branch: git checkout -b modules/{entity-name}

## During Implementation

Step 1: Domain Layer
- [ ] Create domain/{entity}.model.ts (commands, enums, types)
- [ ] Create domain/{entity}.domain.ts (pure functions)
- [ ] Add domain tests (100% coverage target)
- [ ] Commit: "Module: {entity} domain layer"

Step 2: Infrastructure (Repository)
- [ ] Create application/{entity}.repository.ts (interface + CreateRecord DTO)
- [ ] Create infrastructure/json-{entity}.repository.ts
- [ ] Create infrastructure/postgres-{entity}.repository.ts
- [ ] Create infrastructure/{entity}.repository.factory.ts
- [ ] Add contract tests (verify both adapters behave identically)
- [ ] Commit: "Module: {entity} persistence adapters"

Step 3: Ports & Service
- [ ] Create application/{entity}-*.port.ts (4-5 ports)
- [ ] Create infrastructure/default-{entity}-*.port.ts (4-5 adapters)
- [ ] Create application/{entity}-application-service.ts (5-port DI)
- [ ] Create application/create-{entity}.mapper.ts (DTO → Command)
- [ ] Add service integration tests (all ports mocked)
- [ ] Commit: "Module: {entity} application layer"

Step 4: Integration
- [ ] Wire service into action layer (lib/actions.ts)
- [ ] Add action layer tests (via actions)
- [ ] Verify backward compatibility (existing tests still pass)
- [ ] Update package.json scripts (add test:{entity} suite)
- [ ] Commit: "Module: {entity} action integration"

## After Implementation

- [ ] npm run test:{entity} → all passing
- [ ] npm run test -> all passing (no regressions)
- [ ] TypeScript errors: 0 (npm run lint or equivalent)
- [ ] Documentation updated (if adding to STANDARDIZATION_GUIDE.md)
- [ ] Code review by team
- [ ] Merge to main

## Testing Criteria

| Phase | Commands | Target |
|-------|----------|--------|
| Domain | npm run test:{entity}:domain | 100% coverage |
| Contract | npm run test:{entity}:contracts | Both adapters identical |
| Service | npm run test:{entity}:service | All paths covered |
| End-to-End | npm run test:{entity} | All passing |
| Regression | npm run test | No broken existing tests |
```

---

## File Count Reference for Planning

| Module Type | Files | Est. Lines | Effort |
|---|---|---|---|
| **Simple** (Create only) | 12 | 2000 | 4-5h |
| **Standard** (Create + Update) | 18 | 3500 | 6-8h |
| **Complex** (Full CRUD + queries) | 22 | 5000 | 10-12h |
| **Enterprise** (Schedules + exports) | 25+ | 7000+ | 15h+ |

**Purchases** (Create only): 14 files, 3100 lines, production-ready ✅

---

## Common Patterns Proven

### Pattern 1: Wrapping Legacy Functions in Ports

```typescript
// DEFAULT ADAPTER IN PORT (proven pattern)
import { legacyFunction } from '@/lib/data';

export class DefaultAccountingPort implements IPurchaseAccountingPort {
  async postJournal(order: Purchase): Promise<void> {
    try {
      await legacyFunction(order);
    } catch (error) {
      console.error('Journal posting failed (non-critical):', error);
      // Don't rethrow - swallow errors
    }
  }
}
```

**Works for**: Wrapping any legacy function as side effect or optional operation

### Pattern 2: Pre-Generating IDs at Service Layer

```typescript
// SERVICE ORCHESTRATION (proven pattern)
export class PurchaseApplicationService {
  private idGenerator: IPurchaseIdGenerator;
  
  async createPurchaseOrder(command: PurchaseCreateCommand): Promise<Result> {
    const id = await this.idGenerator.generate(); // ← Get ID before anything
    
    // Validate, calculate, persist (all with pre-generated ID)
    const order = { ...command, id };
    await this.repository.create(order);
    
    return { success: true, id };
  }
}
```

**Works for**: Ensures ID is deterministic before persistence, testable in service layer

### Pattern 3: Repository Contract Tests

```typescript
// CONTRACT TEST (proven pattern)
for (const adapter of [jsonAdapter, postgresAdapter]) {
  const result = await adapter.create(order);
  assert.equal(result.id, order.id, 'should preserve pre-generated ID');
}
```

**Works for**: Ensures both JSON and Postgres behave identically (swap-safe)

### Pattern 4: Service Tests with Full Mocking

```typescript
// SERVICE TEST (proven pattern)
const service = new PurchaseApplicationService(
  mockRepository,      // All methods mocked
  mockAccounting,      // Track calls
  mockSideEffects,     // Verify order
  mockReferenceData,   // Mock lookups
  mockIdGenerator      // Mock ID generation
);

const result = await service.create(command);

assert.equal(mockIdGenerator.calls.length, 1);    // ID generated once
assert.equal(mockRepository.calls.length, 1);      // Persisted once
assert.equal(mockAccounting.calls.length, 1);      // Posted once
assert.equal(mockSideEffects.calls.length, 3);     // 3 side effects called
```

**Works for**: Fully testing orchestration without real I/O

---

## Troubleshooting

### Tests Fail: "Cannot find module"

**Likely Cause**: Port/adapter imports wrong
**Fix**: Verify application layer imports infrastructure via factory, not direct adapter

### Tests Fail: "Repository not using pre-generated ID"

**Likely Cause**: Adapter calling ID generator directly
**Fix**: Repository should accept ID in CreateRecord DTO, not generate it

### Tests Fail: "Side effects not called in order"

**Likely Cause**: Side effects called in parallel or wrong order
**Fix**: Service should await each side effect in sequence; see PurchaseApplicationService

### TypeScript Error: "Circular dependency"

**Likely Cause**: Infrastructure importing from application that imports from infrastructure
**Fix**: Ensure one-way imports: domain ← application → infrastructure

### Action Layer Breaks After Module Extraction

**Likely Cause**: Response shape changed or missing revalidation
**Fix**: Verify action layer calls service, captures result, preserves existing response shape exactly

---

## Success Story (Purchases Module)

```
✅ Purchases module extracted (14 files, 3100 lines code)
✅ All tests passing (npm run test:purchases → 10 passed, 1 skipped)
✅ Backward compatible (action layer response unchanged)
✅ Production ready (in use since implementation)
✅ Patterns proven (5 ports, service orchestration, adapters)
✅ Documentation complete (4 guides, 1800+ lines)
✅ Ready for replication (Sales, Inventory, Accounting, Payroll)
```

---

## Next Action

### Immediate (This Week)
1. Read [SALES_MODULE_GUIDE.md](SALES_MODULE_GUIDE.md)
2. Create `lib/modules/sales/` folder structure
3. Implement Step 1: Domain layer for SalesInvoice
4. Write domain tests (calculateSalesInvoiceTotals, validators)
5. Commit: "Module: Sales domain layer"

### Following Week
6. Implement Step 2: Repository adapters (JSON + Postgres)
7. Add contract tests
8. Implement Step 3: Ports + service + adapters
9. Add service integration tests
10. Commit: "Module: Sales application layer"

### Week After
11. Wire into action layer (handleCreateSalesInvoice)
12. Add end-to-end tests
13. Verify all tests passing
14. Code review + merge

**Estimated Completion**: 2-3 weeks for Sales module

---

## Resources

- **Visual Examples**: Open `lib/modules/purchases/` folder to see production implementation
- **Code Templates**: See FOLDER_STRUCTURE_GUIDE.md → "File Template Repository" section
- **Decision Tree**: See STANDARDIZATION_GUIDE.md → "Quick Decision Tree for New Modules"
- **Testing Patterns**: See tests/purchases/*.test.ts for working examples

---

## Team Communication

### When Sharing This Document

> "We've extracted the module architecture pattern from our Purchases implementation and documented it for organizational reuse. Follow the roadmap in IMPLEMENTATION_ROADMAP.md, start with SALES_MODULE_GUIDE.md, and reference lib/modules/purchases/ for working examples. All tests passing, production ready."

### For Architecture Questions

> "See MODULE_ARCHITECTURE.md for the 3-layer structure and 5 required ports. For specific domain implementation, see STANDARDIZATION_GUIDE.md examples."

### For Implementation Help

> "Follow SALES_MODULE_GUIDE.md step-by-step. If stuck on a specific layer, check lib/modules/purchases/ for the proven pattern."

---

## Document Cross-References

- Questions about folder structure? → [FOLDER_STRUCTURE_GUIDE.md](FOLDER_STRUCTURE_GUIDE.md)
- Questions about patterns? → [MODULE_ARCHITECTURE.md](MODULE_ARCHITECTURE.md)
- Implementing Sales? → [SALES_MODULE_GUIDE.md](SALES_MODULE_GUIDE.md)
- Implementing other domains? → [STANDARDIZATION_GUIDE.md](STANDARDIZATION_GUIDE.md)
- Questions about what to customize? → [STANDARDIZATION_GUIDE.md](STANDARDIZATION_GUIDE.md) → "Decision Tree"
- Need working code examples? → `lib/modules/purchases/` (production code)

---

## Final Checklist

- [x] Purchases module implemented and tested ✅
- [x] 5 ports decoupled (Repository, Accounting, SideEffects, ReferenceData, IdGenerator) ✅
- [x] 4 comprehensive documentation files created ✅
- [x] Sales module walkthrough guide completed ✅
- [x] Standardization guide with reuse patterns completed ✅
- [x] Folder structure and naming conventions documented ✅
- [x] Implementation roadmap defined ✅
- [ ] Sales module implementation (next)
- [ ] Inventory module implementation (after Sales)
- [ ] Accounting module implementation (after Inventory)
- [ ] Payroll module implementation (after Accounting)

**Status**: Ready for organizational rollout. All patterns proven. Documentation complete.