Automatic architecture mapping

Once an organization connects its AWS account and its GitHub source control, Landfall derives an Architecture Map from what it can already read — services, dependencies between them, and the external services they depend on — without requiring a single uploaded document. This page is a transparency page, not a connection wizard: it explains what a mapping pass reads, what it infers, what additional permissions would improve it, and how to review or correct the result. Connecting AWS/GitHub itself is covered on their own setup pages (/integrations/aws, /integrations/github).

What a mapping pass does

A pass runs once daily by default, again whenever an AWS or GitHub connection changes, and on demand from an organization admin. Every pass is read-only against both providers — never a write, never a remediation — and is itself recorded as a MappingPass row, so an operator can see when passes ran, what they cost, and what they covered without needing database access.

What it reads from AWS

Four read-only operations enumerate what is running: ListClusters and ListServices (ECS) discover running services; DescribeLoadBalancers and DescribeTargetGroups (ELBv2) discover routing edges, which are then matched by name against a discovered ECS service to infer a routes-to relationship. Every one of these is a List* or Describe* call — no mapping pass can ever create, modify, or delete anything in a customer's AWS account, verified structurally, not only by observed behavior.

Known gap, not silently narrowed: managed AWS data/messaging services (RDS, ElastiCache, SQS/SNS, S3, DynamoDB) and Lambda are not yet discovered — no read operation exists for them today. This is real follow-on work, not an oversight, and will widen this page's coverage table when it ships.

What it reads from GitHub

No new GitHub operations were needed — the existing installation-repository listing, code search, and file-read operations already cover this: listInstallationRepositories enumerates what the installation can see; searchCode and getFileContents find and read dependency manifests (package.json today) and scan for recognizable vendor SDK imports and environment-variable references. A manifest entry is the strongest signal (a declared, intentional dependency); an import or env-var reference is weaker (it could be dead code) and is scored accordingly.

A monorepo is never flattened into one service: a match is attributed to the nearest directory containing its own manifest file, so a repository with several independently deployable services is mapped as several elements, not one.

The same real thing, seen twice

When a GitHub repository's name confidently matches a service Landfall already derived from AWS (an exact or near-exact name match, the same threshold described below), the GitHub-side evidence is attached to that same element as a second attestation — never written as a second, duplicate element. An engineer reviewing the result sees one service with two independent pieces of evidence behind it.

The 0–1 match score, and why 90%

Every candidate is scored 0 to 1 before it is written: an exact, directly-observed AWS resource scores 1 (it isn't a guess — the resource genuinely exists); a GitHub name correlation or a target-group-to-service match uses a name-similarity score, where an exact case-insensitive match scores 1 and a weaker, substring match scores 0.5. Only a score at or above 0.9 is written; anything below that is recorded as a skipped, low-confidence observation instead of being asserted. This reuses the same cutoff value already shipped for the platform's one other example of this kind of inference (automatic repo-to-service mapping) — reused for plausibility, not because it is proven in advance to hit exactly 90% real-world precision on this feature's own evidence types. The actual bar is validated against a hand-verified reference topology, and the cutoff is raised if that measurement falls short.

Multiple AWS accounts, multiple connections

An organization is not assumed to have exactly one AWS account or one GitHub installation. Every configured connection — and every declared AWS member account under a management-account connection — is read and budgeted independently, and every derived element's identity carries which connection (and account) it came from, so two accounts' identically-named services are never confused with one another.

Keeping up with reality

A rescrape revises the map in place: an unchanged service is simply reconfirmed, a new one is added, and one that can no longer be found is recorded as no longer observed — never deleted automatically on a single pass, because a transient read failure and a genuine decommission look identical in one observation. A human's correction to any derived element always outranks a later rescrape's contradicting guess; the contradiction is raised as a conflict for a human to settle, never silently overwritten.

Operational safety

Each connection gets its own budget — 500 provider calls per pass by default — checked before every read. Reaching it stops that connection's reads cleanly, keeps whatever was already found, and records what was skipped; it never continues unbounded and never discards partial results. A provider read failure degrades coverage for that one read alone and is reported, rather than failing the whole pass.

Reviewing and correcting what was inferred

An organization admin can trigger a pass on demand and inspect any pass's cost and coverage without database access. Every derived element's evidence — which provider, which read, what was actually seen — is available by id, so an engineer (or the map's own viewer, once it ships) can always answer "why does Landfall think this?" without asking Landfall's own operators.