Onboarding guide

MMCA.Common + MMCA.ADC, Onboarding Guide

A teaching guide for an experienced .NET engineer who is new to this codebase. It walks every first-party type, explaining not just what each type is but how it works and why it was built that way, introducing each project-specific concept the first time it appears, and connecting the code to a 34-category architecture-evaluation rubric as it goes.

Ground rule for this guide: every statement is traceable to source actually read, cited as path/File.cs:line. Where the source can't settle a question, the text says so explicitly ("Not determinable from source: …") rather than guessing. The existing docs (Architecture/ArchitecturalAnalysis.md, ADRs/, per-project CLAUDE.md) are used as a map and cross-check, but source code is ground truth, where a doc and the code disagree, the code wins and the discrepancy is noted.

Building a new app rather than reading an existing one? This guide is a tour of code that already exists. The adoption path is the getting-started guide, which scaffolds the solution with dotnet new mmca-app; the phase-by-phase detail behind it is the build-by-hand walkthrough, whose worked companion is the runnable MMCA.Helpdesk seed.

How the guide is organized, two axes

The guide has two organizing axes that work together.

1. Primary axis, functional grouping. Every type lives in exactly one functional group: the capability or cross-cutting concern it most exists to serve. The 27 group chapters (group-01-*.md … group-27-*.md) are sequenced roughly topologically, foundational, widely-depended-on concerns first (Result → domain blocks → querying → events → CQRS → …), then the ASP.NET/UI/Aspire edges, then the MMCA.ADC business modules that build on all of it, then the test infrastructure. The full assignment of every type to its group is 00-group-taxonomy.md.

2. Secondary axis, dependency leveling within a group. Inside each chapter, the per-type sections run in ascending Level (a longest-path topological layering over first-party dependencies), so you meet a type only after the first-party types it depends on.

First-party type = any type declared in MMCA.Common or MMCA.ADC source. The .NET BCL and external NuGet packages are not first-party, they are "external Level 0", explained once in the primer, never per class.

Level(C) = 0                              if C references only external (BCL/NuGet) types
Level(C) = 1 + max(Level(D)) over all first-party D that C depends on

When a type must reference a first-party type whose home group appears later, that forward reference is allowed (functional cohesion can outrank strict progressive disclosure) and is cross-linked. Thirty-six dependency cycles exist (mutually-dependent types, e.g. an aggregate root and its child entity with bidirectional EF navigations); each is kept whole within a single group and called out where it occurs. They are listed in the dependency manifest. Three of them are name-collision artifacts rather than real dependencies: the identically-named pairs SelfHttpWarmupTask (MMCA.ADC.Engagement.Service/SelfHttpWarmupTask.cs:23 and MMCA.ADC.Identity.Service/SelfHttpWarmupTask.cs:23), Priority (MMCA.Common.Infrastructure.Tests/Persistence/Conversions/EnumerationValueConverterTests.cs:89 and MMCA.Common.Shared.Tests/ValueObjects/EnumerationTests.cs:122), and GateTestContext (MMCA.Common.Infrastructure.Tests/Persistence/AuditTrail/AuditTrailModelGateTests.cs:76 and MMCA.Common.Infrastructure.Tests/Scheduling/SchedulerModelGateTests.cs:71) are distinct types the globally-unique-name fallback described below cannot tell apart, so each resolves to the other.

How the inventory & leveling were computed

The type inventory and dependency graph are produced mechanically by a small Roslyn syntactic parser (Tools/invtool/), so the type list, namespaces, and file:line are exact and reproducible. Edges are resolved by namespace-aware name matching; ~96% bind by namespace visibility, the rest by a globally-unique-name fallback (586 edges), and 38 references are dropped as ambiguous. The functional grouping is then applied mechanically (Tools/invtool/classify.ps1 → 00-group-taxonomy.md), so every one of the 4,257 distinct type nodes maps to exactly one group with no silent drops. See the manifest's accuracy note for residual caveats.

Chapters

Front matter

Group chapters (primary axis)

DevOps & operations chapters

Back matter

Legend, how to read a type section

Every type gets one section using this template:

{TypeName}

{Assembly} · {namespace} · {file:line} · Level {n} · {kind}

• What it is: one or two plain-language sentences.
• Depends on: first-party types (linked) and notable externals.
• Concept introduced: taught from first principles the first time a pattern appears; otherwise cross-references where it was introduced. Relevant rubric categories are tagged inline as [Rubric §N, Name].
• Walkthrough: members in teaching order (fields → constructor/factory → key methods), with line numbers and the mechanism.
• Why it's built this way: design rationale; cites the relevant ADR when one applies.
• Where it's used: a forward pointer to consumers.
• Caveats / not-in-source: anything uncertain, stated explicitly.

• Cross-links. A first-party type named in prose links to its section, e.g. Result. The target is computed from the type's group (see 00-group-taxonomy.md); within a chapter, links are same-page anchors.
• Sibling families. Near-identical types (per-entity Add*/Remove*/Update* commands, *DTOMapper, *Validator families) may share one ### A, B, C section that teaches the shared shape once, with a per-member File:Line table so every type stays individually cited.
• [Rubric §N, Name] tags. These connect the code to the 34-category rubric introduced in the primer. A tag explains the category and how this code embodies (or under-uses) it, it does not score it. Scoring lives in the separate ArchitectureEvaluation-*.md reports.

Suggested reading paths

• Framework-first (recommended). Primer → group-01 → upward. You meet the MMCA.Common foundations before the MMCA.ADC features that build on them; this matches dependency order across and within groups.
• "I need to touch the ADC Conference module." Primer → skim group-01/02/05 (Result, domain blocks, CQRS) → then Conference Domain → Application → UI.
• Capability deep-dive. Jump straight to the group for the concern you care about, persistence, auth, events/outbox, notifications, navigation populators, etc. Each chapter opens with a "how this capability is implemented" overview before the per-type sections.
• Rubric-driven (architecture review). Read the primer's rubric section, then follow the [Rubric §N] tags; the coverage audit maps every category to where it's first explained.
• Operations / DevOps. Primer → the devops-* chapters.
• "I want to build my own app on the framework." Not this guide: start at the getting-started guide, then come back here for the internals behind whichever pattern you land on.

The companion projects (context)

MMCA.Common , shared framework, published as 15 NuGet packages (DDD/Clean Arch/CQRS base classes)
   ├── consumed by MMCA.ADC   (Atlanta Developers Conference app, the focus of this guide)
   └── consumed by MMCA.Store  (e-commerce app, out of scope here)

This guide covers MMCA.Common (the framework) and MMCA.ADC (one consumer). MMCA.Store is out of scope. The dependency arrow is why the Common framework groups (1–16) come before the ADC business-module groups (17–25); the late-added Common Device Capability layer (26, a framework concern appended after the business modules) and the test infrastructure (27) come last.