Advanced 30 min read

Document the Architecture

By the end of this lesson, you'll be able to:

Write architecture documentation that helps a new developer navigate this project
Apply Module 41's technical design document principles to a completed system, not just a plan
Distinguish documentation worth writing from documentation that will immediately rot

Prerequisites: "Write the Test Suite"

A layer map, for fast orientation

# Project Delivery Tracker — Architecture Overview

## Layers
- Domain (trigger handlers): ProjectTriggerHandler,
  MilestoneTriggerHandler, TimeEntryTriggerHandler,
  SupportCaseTriggerHandler — one per object, dispatch only.
- Service: ProjectHealthService, MilestoneStatusService,
  ProjectSupportBurdenService — all business logic lives here.
- Selector: ProjectSelector, MilestoneSelector, TimeEntrySelector,
  SupportCaseSelector — all SOQL lives here.

## Async
RecalculateProjectHealthBatch runs nightly at 3:00 AM as a safety
net alongside real-time trigger-driven recalculation.

## Integrations
SlackNotificationQueueable sends an outbound webhook when a
Project's health becomes At Risk.

A new developer reading this can find any piece of logic in seconds — "where's the Slack integration?" has one obvious answer, rather than requiring a search through the whole codebase.

What NOT to document

This overview deliberately does not restate what a service class is (Module 43 already teaches that), or copy each field\'s definition from the data model (the schema itself is the source of truth for that). Documentation that duplicates something already easy to look up will drift out of sync the first time that thing changes, becoming actively misleading rather than helpful — Module 41\'s "write down the WHY, not what\'s already obvious from the code" principle, applied here to an entire project.

Documentation as the final proof the architecture worked

Being able to summarize this whole project in one short layer map is itself evidence that Module 43\'s layered architecture succeeded here — a genuinely tangled, ad hoc codebase resists this kind of clean, short summary. If writing this overview had been difficult or required exceptions and caveats everywhere, that would have been a signal the architecture wasn\'t actually being followed consistently.

Exercise

As a comment, explain why this lesson's architecture overview does not re-explain what a "selector class" is in general, even though that concept is central to the project.

Show hint

Think about where that general explanation already lives.

APEX

Document the Architecture Quiz

1. What does the ease of writing a short, clean architecture overview for this project actually demonstrate?

That the layered architecture was actually followed consistently throughout the project, rather than abandoned in places That documentation is always easy to write regardless of code quality Nothing - documentation difficulty has no relationship to architecture quality That the project has too few features to be worth documenting

My Notes

Questions about this lesson

No questions yet — be the first to ask.

Summary

This lesson documents the completed architecture for a developer joining the project later — Module 41's technical-design-document discipline, applied retrospectively to explain a finished system rather than propose a new one.

← Write the Test Suite Final Review and Presentation →