Architecture Analysis & Mapping

The architecture analysis of a repository is CodeDD's reconstruction of how that repository is built and what it could carry, read from the code and configuration themselves. Most codebases have no current architecture documentation. CodeDD produces an interactive map of components, technologies, relationships and external systems, says what kind of repository it is, and states how much growth it supports today, with the evidence behind each statement.

This page covers a single repository, on the Architecture tab of an audit. For the portfolio view across many repositories, see Estate Map & Portfolio Architecture.

What does the architecture analysis show for one repository?#

The architecture analysis of a repository has seven parts, all on the Architecture tab of its audit.

• Architecture graph and table. An interactive map of the components and the relationships between them, with a table view of the same data.
• Module dependencies. The import structure between the repository's own modules.
• Details panel. For a selected component or line: what it is, what it connects to and the evidence behind it.
• Technology stack. The languages, frameworks, databases and tools detected, with scope, version and detection confidence.
• External systems. Third-party services the repository integrates with.
• Key metrics and written assessment. Component, relationship and technology counts, coupling, primary communication style and single points of failure, followed by a written summary.
• Repository profile and Scale readiness. What the repository is (its kind), how it is built (its style) and its Scale readiness tier.

A closing panel, "What the analysis could establish", states which parts of the model were found, verified absent, or could not be assessed. The sections below explain each part.

How do I read the architecture graph?#

The architecture graph of a repository draws its components as boxes, grouped in frames, and its relationships as lines.

For services and monorepos, each frame is one deployable unit: something the repository builds and ships, such as a container image, a function or a static site. The modules that run inside it sit within the frame. Count the frames, not the boxes, to tell a monolith from a distributed system: a monolith is one frame however many modules it holds. Frontend apps are grouped by role, libraries and command-line tools by public API and internals, and infrastructure repositories by domain.

Box color is the component's domain. External systems have a dashed outline because they sit outside the repository. Data stores and brokers appear in bands beneath the frames. Line color is the relationship type, and line style is the evidence (see the evidence levels below).

Tests, CI, build and deployment files, migrations and configuration are collapsed by default. The "Show supporting artefacts" toggle draws them in their own band. They are always shown for infrastructure repositories, where configuration is the content. Components with no drawn relationship appear after the connected ones: no relationship was found in the files analyzed, which does not prove there is none.

You can search, pan, zoom, hide AI-inferred relationships, highlight structurally critical components and download the graph as SVG or PNG. The table view lists the same components and relationships, supporting artefacts included, and the graph works from the keyboard.

What are deployable units, process roles and backing services?#

A deployable unit in the architecture analysis is something the repository builds and ships on its own, identified from deployment definitions such as Dockerfiles, compose files, Procfiles and serverless templates.

Three related ideas are kept apart so that the count of deployables is not inflated:

A web process and a worker built from the same image are one deployable with two roles. A Postgres or Redis container is a backing service, not an application. Development-only files, such as local compose overrides and dev containers, are ignored.

Where the evidence cannot be classified, CodeDD reports it as unknown instead of reading it as nothing. For example, a build of application code that is neither clearly an application nor a library is listed as unrecognized. When no deployable units can be determined (for example in an audit run without a deployment census), the graph is grouped by domain and a note above it says why.

What do the evidence levels on relationships mean?#

The evidence level of a relationship in the architecture graph tells you what kind of support it has. It is shown by line style and in the legend.

"Hide AI-inferred" removes every relationship without static evidence, which leaves what the code proves. Use it before drawing conclusions about coupling. The legend lists only the levels present in the graph you are viewing.

The same principle applies to external systems and technologies: a finding that the files corroborate carries more weight than one only the AI analysis claims. AI claims the files do not corroborate are kept as candidates for reference. They are never used to decide the repository's kind, style, tier or criticality.

What does confidence mean in the architecture analysis?#

Confidence in the architecture analysis is the analysis's own estimate that a finding is real, shown as a percentage on components, relationships and technologies. It is not a quality score, and it does not say a technology is good or a design is sound.

On a technology, the bar is the detector's confidence that the technology is used. A technology without a figure reads "n/a". On a component or relationship, the details panel shows the confidence reported for it, or "Not reported".

Standard, well-known stacks tend to score higher. Heavily customized systems and in-house frameworks may score lower, particularly for inferred relationships.

Confidence and evidence level answer different questions. The evidence level says what kind of support exists (the code, an AI reading of the code, or the AI's claim alone). Confidence says how sure the analysis is. Read them together, and prefer a solid line with high confidence over a dotted line with the same figure.

How does the architecture analysis work?#

The architecture analysis of a repository works deterministic-first: facts are read from files, and AI is used to label, describe and propose, never to decide a fact that files can settle.

1. Read the evidence. CodeDD reads manifests and lockfiles, configuration, deployment definitions, infrastructure code and the import structure between modules. This yields the technology inventory, the deployable units and the module dependencies.
2. Classify. The repository kind is decided from that evidence. The Scale readiness checks are run against it. A repository's style is decided from deployment evidence where it exists.
3. Synthesize. AI analysis names the components, describes their responsibilities, and proposes relationships and external systems. Each proposal is then checked against the files it cites.
4. Present. The graph is built with each relationship marked by the evidence behind it, together with the written summary.

Three rules follow from this. AI never sets a repository's kind, tier or the Scale readiness requirement states without deterministic evidence. A claim the files do not corroborate is kept apart as a candidate. And unknown is not absent: where CodeDD cannot see a fact, it says "not assessed" rather than "none".

Architecture analysis also runs as part of the Audit Process Overview, after file analysis and before Cross-File Contextualization.

What does the details panel show?#

The details panel of the architecture graph opens when you select a component or a line, and shows what it is and why it is in the graph.

For a component, the panel lists what depends on it and what it depends on (each entry opens that component), its level, the deployable unit it runs in and why, its detection confidence, whether it is structurally critical and why, and the evidence behind each of its relationships. For an external system, it lists who references it and on what basis.

For a line, the panel shows the relationship type, its direction, its evidence level and confidence, and the evidence itself.

"Structurally critical" is computed from the shape of the graph: a component that connects otherwise separate parts, has many dependents, or is a single point of failure. The AI's strength label is not criticality. Select a critical component to see why, and check the evidence of the relationships involved, since some may be AI-inferred. "Show critical paths" dims everything except these components and the links between them.

On a wide screen the panel sits beside the graph. On a narrower screen it opens over the graph, and on a phone as a sheet at the bottom. Escape or the close button dismisses it.

What are module dependencies?#

Module dependencies in the architecture analysis are the relationships between a repository's own modules, read from static imports rather than inferred by AI. They appear in a second view next to the component graph.

The view also reports structural facts about the import graph: dependency cycles, how stable each module is, and layer-rule violations where a layering convention is visible from naming.

The view appears only where the imports can be read. If CodeDD cannot resolve imports for the repository's main language, it says so instead of drawing an empty graph, because an empty graph would read as "no internal dependencies". It also says when the repository is a single module (nothing to show), when no import graph was stored for the audit, and when an older audit used a resolver that guessed targets by file name. Re-running the audit fixes the last two.

What does the technology stack show?#

The technology stack of a repository lists the technologies detected in it, grouped by area: languages and runtimes, frontend, backend and APIs, databases and storage, messaging and jobs, infrastructure, and build, test and delivery tooling.

Each technology shows its detection confidence as a bar, its scope and, where a lockfile or manifest gives one, its version. Scope says where the technology is used: runtime, development, test or build. A test or development-only dependency never makes a repository a service.

Open a technology to see its category, the files and kinds of evidence behind it (manifest, lockfile, configuration or source code) and the detector's evidence lines. A technology marked "Listed by the technology inventory only" was found in the inventory but is not named in the detector's summary.

The inventory supports the other findings. It feeds the repository kind, the Scale readiness checks and, across a portfolio, the shared-technology views described in Estate Map & Portfolio Architecture.

What are external systems in the architecture analysis?#

External systems in the architecture analysis are third-party or out-of-repository services the repository integrates with, such as payment providers, email services, storage, monitoring and identity providers. They are drawn with a dashed outline.

A managed database or message broker appears with the data stores instead. In the details panel, an external system lists which components reference it and on what basis.

External systems are grounded: the analysis keeps one that the repository's files support (a configuration key, an SDK in the manifest, an endpoint reference) and sets aside one that only the AI analysis names. The set-aside ones remain visible as candidates for reference.

An external system is a fact about the repository's code. It does not mean the integration is healthy, licensed or contractually in place. It also may not show an integration that is loaded dynamically at runtime or configured entirely outside the repository.

What do the key metrics and the written assessment show?#

The key metrics of the architecture analysis are tiles above the repository profile. They show the number of components, relationships and technologies, plus coupling, primary communication style and single points of failure.

Coupling, communication style and single points of failure are derived from the graph. When the graph represents too small a share of the repository's source packages, or the audit predates the recomputation, the tile reads "Not assessed" with a note instead of a guess. Each tile opens an explanation and the data behind it.

Below the profile, a written summary of the architecture describes the main patterns, scalability indicators and risk highlights, for example single points of failure or missing abstractions. The summary is commentary on the structured findings. When a statement in it matters to a decision, check the graph and the evidence it rests on.

Security vulnerability scanning is a separate feature covered in AI-Powered File Analysis.

What repository kinds does the architecture analysis recognize?#

The repository kind in the architecture analysis says what a repository is. It is decided from deterministic evidence, shown as a chip, and carries the reasons behind it.

"Monorepo" is a modifier rather than a kind: a repository holding several projects or several first-party builds. It shows beside the kind.

The decision uses what the repository ships and declares (for example a package manifest that publishes a library, or a deployment definition that builds a server), not the names of its dependencies alone. A test or development dependency never makes a repository a service.

If the evidence is weak or contradictory, the chip reads "Kind not determined". Unknown is not a service. An audit from before the current classification shows a kind read from its stored technologies, with a note that a re-run gives the full classification.

Why does a repository show 'Not rated'?#

A repository shows "Not rated" for Scale readiness when its kind has no running scale to rate, or when there is not enough evidence to rate it fairly.

Scale readiness measures how a running system handles growth. The tier does not apply to these kinds: frontend, mobile and desktop apps, libraries and SDKs, CLI tools, infrastructure-as-code and GitOps repositories, data pipelines, ML projects and documentation. A library has no traffic to scale, and an infrastructure repository describes where other systems run rather than running at scale itself. Not rated is not a poor result. It means the question does not apply.

A repository can also have "not enough evidence": its files could not be read, or too few checks could run to say anything. Then no tier is shown rather than a guess.

A repository's Not rated status has one further effect in a portfolio. It takes no part in the company tier, although an infrastructure repository can still provide evidence that settles checks in the repositories it provisions.

How is the architecture style of a repository decided?#

The architecture style of a repository is its shape: monolith, modular monolith, service-oriented, microservices, serverless or event-driven. Other values such as library, frontend app and infrastructure as code apply to kinds that are not services.

One style is decided per repository, with its source stated. A style an administrator has set wins. Otherwise strong deployment evidence decides, for example several independently built deployables that call each other. Where deployment evidence is thin or absent, an AI assessment can supply the style, and the product labels it as such. The source is shown as Curated, Deployment evidence, AI assessment or No evidence.

Where sources disagree, the disagreement is shown, not resolved silently. If nothing supports a style, it reads Unknown.

The style never sets the Scale readiness tier. A monolith can reach a high tier and a microservices system can sit at the lowest, because the tier is about operational capability. The two facts are shown separately for that reason.

What is Scale readiness for a repository?#

Scale readiness for a repository is how much growth that repository supports today, judged from what runs in its code and configuration. It is shown as a tier from T1 Foundational to T5 Hyperscale.

The tier is the result of a checklist, not a score. A repository reaches a tier when every requirement up to it is evidenced in every area that applies to it, and its tier is its lowest area. Each requirement is a yes-or-no capability, and each is shown with the files it rests on.

Tiers are cumulative: a repository at T3 has what T2 requires, too. Some higher-tier checks are not built yet. The product says "Not checked yet" for them and never counts them against a repository.

The repository's Architecture tab shows the tier with its certainty, which area limits it, what would lift it, and the checklist behind each area. In an organization, "See in company context" opens the company's Scale readiness scoped to this repository. If the company's view of the repository differs from its own analysis (links from other repositories count there), the card says so.

What are the six areas of Scale readiness?#

The six areas of Scale readiness each look at one aspect of how a system runs, and each is judged separately.

The list of requirements behind each area is versioned, and a tier is always quoted with its version. The areas are the same for a company, where each area gets its own level and the company tier is the lowest.

An area that does not apply to a repository is left out of its minimum. For example, a repository with no database is not held back by data requirements.

What do Met, Not met, Not assessed and Doesn't apply mean?#

The four states of a Scale readiness requirement say what the analysis found for one capability in one repository, always with the files it read.

• Met. Evidence of the capability was found. The requirement shows what counts as met and the files that show it.
• Not met. CodeDD checked where the capability would be declared and did not find it.
• Not assessed. The state could not be established. Either it needs confirmation, because the capability lives outside the audited repositories (for example a platform setting or a separate infrastructure repository), or it is not checked yet because CodeDD has no check for it.
• Doesn't apply. The requirement is irrelevant to this repository, with the reason shown.

Not assessed never counts against a tier. It cannot confirm one either. A platform that supports a capability is not treated as having it, so a capability that the platform could provide but the repository does not show reads "to confirm", not Met.

Not met is only reported where a check could look. If the files could not be read, the answer is Not assessed. Adding the infrastructure repository to the audit often settles many "to confirm" items.

What does 'at least' (T2+) mean compared with an exact tier?#

A Scale readiness tier is either exact or "at least", and the difference is whether the next tier was ruled out.

Exact means the next tier was checked and at least one of its requirements is Not met, so the repository does not reach it.

At least means the tier is proven but the next one could not be verified, so the true tier may be higher. It is shown with a plus, as in T2+, and the tooltip reads "at least Tier 2". The reasons are usually that a next-tier requirement depends on something outside the audited repositories, or that CodeDD does not check it yet. "Not yet verified" means nothing missing was found but some evidence sits elsewhere. "Next tier: Not checked yet" means the check does not exist.

Treat an at-least tier as a lower bound. It must not be compared with an exact tier as if they were equal; benchmarks and exports flag it.

Is a higher Scale readiness tier better?#

A higher Scale readiness tier is not better. A tier describes scale, not quality, and it should match the growth plan.

Higher tiers add capability at a cost in complexity, tooling and operations. A back-office tool used by a few hundred people can sensibly be Foundational or Established. Building the machinery of a higher tier for a product that does not need it is wasted effort.

For each next-step the product says what it would add and when the step is not needed. Examples are that one well-sized server carries the peak load and one team ships, or that customers are in a single region with no data-residency obligation. Read the tier against your own growth plan. For an acquirer or investor, the useful question is whether the tier fits the plan, not whether it is high.

The tier is also separate from code health. A well-written application can be Foundational, and a poorly written one can run on a sophisticated platform.

What lifts a repository to the next tier?#

What lifts a repository to the next tier is a short list of requirements, split into those to build and those to confirm.

• To build. CodeDD checked and did not find the capability. This is work to do.
• To confirm. The capability may already exist outside the audited repositories. This is information to provide, usually by auditing the infrastructure or deployment repository too.

"Limited by" names the area and the specific missing capability that holds the next tier. The lift list is ranked and counts distinct requirements. It does not estimate effort, and it does not tell you the lift is worthwhile; read it with the "when it is not needed" note.

A tier can also rise without any change to the product, for instance when an audit includes the repository that defines the infrastructure and thereby settles checks that were "to confirm".

What does 'What the analysis could establish' mean?#

"What the analysis could establish" is a panel on the Architecture tab that states, for each facet of the architecture model, what the analysis could determine. The facets include deployable units, modules, interfaces provided and required, messaging channels, data stores, external systems and technologies.

• Found. The facet has entries, read from the files or inferred by a rule or by the AI analysis.
• None found. A detector that applies to the repository read every file it matched and found nothing. This is a verified absence.
• Not assessable. Nothing decided the facet. For example, no detector reads one of the repository's languages, a detector did not read every file it matched, or the deployment census did not run. The reason is shown.

Not assessable is not none. If a facet reads Not assessable, absence in the graph says nothing about the repository. This is the main way to judge how much weight the rest of the page deserves for a given repository.

What does 'Derived from X of Y files analysed' mean?#

"Derived from X of Y files analysed" is a coverage note under the architecture graph. It states how many of the repository's files the graph is built from. A repository that is large relative to the files analyzed will have a less complete graph.

The note may add how many source packages the graph represents, how many files were truncated, and whether it is a fallback graph because the AI synthesis was unavailable. For very large repositories the file count is capped and shown as such.

Coverage matters when you interpret absence. A missing relationship in a graph built from a fraction of the files is weaker evidence than one in a graph built from nearly all of them. Some figures, such as coupling, are withheld with a "Not assessed" note when coverage is too thin to support them.

Related coverage statements appear elsewhere: the Not assessable states above, and the detection coverage disclosed for a whole portfolio in Estate Map & Portfolio Architecture.

Why does an older audit show 'previous method' or 'not re-analysed', and how do I re-run it?#

An audit analyzed before the Scale readiness requirement checks existed shows its tier labelled "(previous method)", without the requirement checklist. Within a portfolio, such a repository counts as not re-analysed.

The previous method shows a tier but cannot show which requirements were met and which files support them. To see the checklist, re-audit the repository. Doing so also refreshes the repository kind, the style decision and the module dependencies, which older audits may lack. The tier may differ after a re-run, because it is now derived from named requirements.

Audits run with the CodeDD CLI work the same way. The CLI extracts the deterministic facts on your machine and the CodeDD cloud completes the analysis. An audit run with an older CLI version may not carry every fact that a check needs; checks it cannot support read Not assessed rather than Not met. Update the CLI and re-run to close those gaps.

Re-running is a deliberate action on your cadence. Audits are not continuous monitoring; see Audit Process Overview.

What are the limitations of the architecture analysis?#

The architecture analysis is static: it reads code and configuration, not runtime behavior. These limits follow from that.

• Data flows are inferred, not measured. Nothing is observed in production.
• Runtime configuration and platform settings are invisible. Anything defined outside the repository, such as cloud settings applied by hand, appears as Not assessed.
• Dynamically loaded components may be missed, as may integrations assembled at runtime.
• Split systems need each part audited. A system split across repositories is analyzed per repository. Relationships between repositories appear only in a portfolio, where the group audit combines them.
• Custom frameworks may not be recognized, which lowers confidence in what is inferred.
• Some languages have no import resolver, so module dependencies cannot be drawn for them.
• The Scale readiness checklist is not complete. Some higher-tier checks are not built yet.
• A tier is not a guarantee. It reports what the code shows, not load-test results or uptime.

Use the architecture analysis to guide diligence questions and focus review, and confirm anything decisive with the engineering team.

What happens to my source code during architecture analysis?#

During architecture analysis, the repository clone is temporary, and it is wiped when the audit finishes. Only findings, scores and metadata persist: component names, relationships, technologies, file paths and counts. Source code and snippets are not stored.

Cloud audits clone to an isolated processing environment, and a CLI audit analyzes on your own machine so that source does not leave your infrastructure. See Secure Data Deletion for the deletion process and Repository Connection & Security for how repositories are accessed.

Frequently asked questions#

These are short answers about the architecture analysis of a single repository, covering ratings, tiers, evidence levels and coverage.

Why is my repository not rated for Scale readiness?#

The Scale readiness tier of a repository does not apply to libraries, CLI tools, frontend, mobile and desktop apps, infrastructure and GitOps repositories, data and ML projects, and documentation. These have no running scale to rate. A repository can also be unrated when its files could not be read. Neither is a poor result.

Does a high tier mean the code is good?#

A high Scale readiness tier does not mean the code is good. The tier measures operational scale capability, and code quality is measured separately by the Code Health Score. A higher tier is also not better in itself: it should match the growth plan.

What is the difference between T2 and T2+?#

T2 is an exact tier: the next tier was checked and ruled out. T2+ means at least Tier 2: the tier is proven, but the next one could not be verified, so the repository may be higher. Do not compare T2+ with an exact T2.

Why does a requirement say 'Not assessed' instead of 'Not met'?#

A Scale readiness requirement reads Not assessed when the analysis could not establish the answer, for example because the capability would be configured outside the audited repositories, or CodeDD has no check for it yet. Not met is reserved for a capability that was checked for where it would be declared and not found.

Why is a relationship drawn as a dotted line?#

A dotted line in the architecture graph marks a relationship with no static evidence: it is either the AI's claim alone or from an audit that predates evidence grading. Verify it before relying on it, or use "Hide AI-inferred" to remove such lines.

Does a component with no drawn relationship have no dependencies?#

A component with no drawn relationship in the architecture graph was not found to have one in the files analyzed. Check "What the analysis could establish" and the coverage note: if the facet is Not assessable or coverage is partial, absence is not evidence.

Why does the graph show one box for my whole service?#

The architecture graph draws one frame per deployable unit. A monolith is one frame, and its modules sit inside. Several processes built from the same image, such as web and worker, are roles of that one unit, not separate services.

Is a shared database or technology a dependency?#

Within one repository the graph shows the data stores a component uses. Across repositories, sharing a technology is never treated as coupling; see Estate Map & Portfolio Architecture.

How can I get a fuller picture of my architecture?#

Include the infrastructure and deployment repositories in the audit, re-audit repositories analyzed before the requirement checks, and update the CLI if you use it. Each of these turns "to confirm" and "not re-analysed" results into real findings.

Can I download the architecture graph?#

The architecture graph of a repository has SVG and PNG download buttons. The table view lists the same components and relationships, and the Scale readiness checklist of a portfolio can be exported as CSV.

Does the architecture analysis scan for security vulnerabilities?#

The architecture analysis does not scan for security vulnerabilities, which is a separate feature; see AI-Powered File Analysis.

Related guides#

These pages describe the audit stages around the architecture analysis of a repository and its portfolio view.

• Estate Map & Portfolio Architecture
• Cross-File Contextualization
• Audit Consolidation & Risk Scoring
• AI-Powered File Analysis
• Enterprise Data API