archlens/CONTEXT.md

Archlens — Domain Glossary

This file defines the canonical language of the Archlens domain. No implementation details — just terms and their meanings.

Core Concepts

• CodeGraph: The aggregate root. A complete representation of a codebase's architecture — all elements, relationships, and module groupings. Can produce filtered subgraphs of itself by module.

• CodeElement: A type-level construct in source code — a class, struct, trait, interface, or enum. Carries a name, kind, location (file + line), visibility, generic parameters, and attributes/decorators.

• Relationship: A directed edge between two CodeElements. Has a kind (inheritance or composition) and references source and target elements.

• Module: A logical grouping of CodeElements. By default inferred from directory structure, overridable via configuration. Represented as metadata on each CodeElement (module_path), not a separate hierarchy.

• Language: The programming language of a source file. A closed set: Rust, CSharp, Python. Determines which analysis strategy is used.

• SourceFile: A file to be analyzed. Carries a FilePath and its detected Language.

Analysis

• AnalysisResult: The output of analyzing a single file — extracted CodeElements, Relationships, and any AnalysisWarnings.

• AnalysisWarning: A non-fatal problem encountered during analysis — unparseable construct, unsupported syntax, etc. Carries file path, line, and message.

• AnalysisConfig: Settings that control what gets analyzed — path excludes, granularity level, module-to-directory mappings.

Output

• RenderOutput: The result of rendering a CodeGraph — a collection of RenderedFiles.

• RenderedFile: A single output artifact — a named file with content (e.g., overview.mmd with Mermaid syntax).

• OutputConfig: Settings that control rendering — format, output path, whether to split by module.

Relationships (kinds)

• Inheritance: A type extends or implements another type (class extends class, struct implements trait, class implements interface).

• Composition: A type owns or depends on another type via a field, property, or constructor-injected dependency.

Metadata on CodeElements

• Visibility: Whether a type is public, private, internal, or other access level. Used as a filterable property, not shown on diagrams by default.

• Generics: Type parameters on a CodeElement. Stored with the element, displayed in simplified form (e.g., Repository<Order> not full generic constraints).

• Attributes: Decorators, annotations, or attributes on a type (e.g., [ApiController], #[derive(Clone)], @dataclass). Stored as metadata, usable for categorization and filtering.

Diagram Levels

• Project level: Dependencies between projects, crates, or packages. Rendered as a flowchart.

• Module level: Dependencies between logical modules (directory-based groupings). Rendered as a flowchart with subgraphs.

• Type level: Individual types with their inheritance and composition relationships. Rendered as a UML class diagram.