# alma-cdk/project architecture

> Architecture diagram of the GitHub repository alma-cdk/project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alma-cdk/project
- Repository: https://github.com/alma-cdk/project

## Overview

1. This repository is a TypeScript CDK library, not an application. Its main public boundary is the `@alma-cdk/project` package exported from `src/index.ts`, with the core runtime centered on AWS CDK constructs and helpers for multi-account, multi-environment deployments.

2. The root orchestration object is `Project` (`src/project/project.ts`). It replaces a plain `cdk.App` and carries project-wide metadata such as project name, author/contact info, default region, and the account strategy. Everything else hangs off this scope.

3. Account and environment configuration are first-class subsystems under `src/configurations` and `src/context`. These modules normalize declared account/environment definitions, resolve the selected account and environment from CDK context, and expose typed accessors so stacks can query configuration consistently instead of reading ad hoc files.

4. Runtime selection is driven by CDK context values, especially `account` and `environment` passed at deploy time. The README shows the intended flow: `cdk deploy -c account=dev -c environment=feature/abc-123`. Those values are interpreted by the context modules and then used to bind the project to the correct AWS account, region, and environment behavior.

5. `AccountWrapper` and `EnvironmentWrapper` (`src/wrapper`) are the structural boundaries for instantiating account-scoped and environment-scoped constructs beneath the `Project`. They provide the composition layer where one project can contain multiple environments and each environment can target one of several accounts.

6. `SmartStack` (`src/smartstack`) is the main stack abstraction. It wraps AWS CDK `Stack` behavior with project conventions: stable vs ephemeral environment handling, termination protection, tag application, and name generation. This is the construct most application stacks are expected to extend.

7. The naming system is a separate subsystem under `src/name`. It provides multiple name formats (`Name`, `UrlName`, `PathName`) plus trimming and max-length logic. This matters because the library is responsible for producing safe AWS resource identifiers across different resource types and account/environment combinations.

8. Tagging is centralized under `src/smartstack/tags` with supporting feature checks. The stack/tag layer computes standard tags such as Account, Environment, Project, Author, Organization, and Contact, and it also contains exclusion/check logic so tags can be applied or suppressed based on resource type and compatibility rules.

9. Feature-flag compatibility is isolated in `src/feature-flags`. The presence of both `legacyTags` and `v0Tags` indicates the library supports migration behavior between major versions, letting the same codebase adapt tag semantics and conventions while preserving backward compatibility for older projects.

10. The remaining folders support the public API: `src/error` adds structured metadata to errors, `src/project` contains account/environment type resolution and region logic, `src/template` and `src/utils` hold reusable helpers, and `src/__test__` plus `test/integration.test.ts` verify the construct behavior end-to-end. Build/release is managed with Projen and GitHub Actions, but the runtime architecture is still primarily a compositional CDK library around `Project -> Wrappers -> SmartStack -> resources`.

Main entry points: [`src/project/project.ts`](https://github.com/alma-cdk/project/blob/main/src/project/project.ts) (Project), [`src/index.ts`](https://github.com/alma-cdk/project/blob/main/src/index.ts) (Package API), [`src/smartstack/stack.ts`](https://github.com/alma-cdk/project/blob/main/src/smartstack/stack.ts) (SmartStack), [`src/smartstack/tags/index.ts`](https://github.com/alma-cdk/project/blob/main/src/smartstack/tags/index.ts) (Stack Tags)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public API"]
  node_src_index["Package API<br/>entrypoint<br/>[index.ts]"]
end

subgraph group_project["Project Runtime"]
  node_src_project_index["Project API<br/>barrel<br/>[index.ts]"]
  node_project_project["Project<br/>orchestrator<br/>[project.ts]"]
  node_project_context["Project Context<br/>context model<br/>[project-context.ts]"]
  node_account_type["Account Type<br/>enum logic<br/>[account-type.ts]"]
  node_environment_type["Env Type<br/>enum logic"]
  node_resolve_region["Region Resolve<br/>region logic<br/>[resolve-region.ts]"]
  node_src_context_index["Context API<br/>barrel<br/>[index.ts]"]
  node_context_account["Account Context<br/>context resolver<br/>[account.ts]"]
  node_context_environment["Env Context<br/>context resolver<br/>[environment.ts]"]
  node_account_wrapper["Account Wrapper<br/>scope wrapper<br/>[account.ts]"]
  node_environment_wrapper["Env Wrapper<br/>scope wrapper<br/>[environment.ts]"]
end

subgraph group_stack["Stack Conventions"]
  node_smartstack_stack["SmartStack<br/>stack abstraction<br/>[stack.ts]"]
  node_smartstack_name["Stack Names<br/>naming helper<br/>[index.ts]"]
  node_smartstack_tags["Stack Tags<br/>tagging subsystem<br/>[index.ts]"]
  node_smartstack_termination["Termination<br/>safety helper<br/>[index.ts]"]
  node_name_system["Name System<br/>naming subsystem<br/>[index.ts]"]
  node_feature_flags["Feature Flags<br/>compat layer<br/>[index.ts]"]
end

subgraph group_support["Support Modules"]
  node_error_add["Error Metadata<br/>error helper<br/>[add.ts]"]
  node_template_index["Template Utils<br/>template helper<br/>[index.ts]"]
  node_utils_find["Shared Utils<br/>utility helpers<br/>[find.ts]"]
end

node_src_index -->|"exports"| node_src_project_index
node_src_index -->|"exports"| node_src_context_index
node_src_index -->|"exports"| node_smartstack_stack
node_src_index -->|"exports"| node_name_system
node_src_index -->|"exports"| node_feature_flags
node_src_index -->|"exports"| node_error_add
node_src_project_index -->|"builds"| node_project_project
node_src_project_index -->|"types"| node_project_context
node_project_project -->|"stores"| node_project_context
node_project_project -->|"uses"| node_account_type
node_project_project -->|"uses"| node_environment_type
node_project_project -->|"resolves"| node_resolve_region
node_src_context_index -->|"exports"| node_context_account
node_src_context_index -->|"exports"| node_context_environment
node_context_account -->|"coordinates"| node_context_environment
node_context_account -->|"binds"| node_account_wrapper
node_context_environment -->|"binds"| node_environment_wrapper
node_project_project -->|"contains"| node_account_wrapper
node_account_wrapper -->|"contains"| node_environment_wrapper
node_environment_wrapper -->|"hosts"| node_smartstack_stack
node_smartstack_stack -->|"applies"| node_smartstack_name
node_smartstack_stack -->|"applies"| node_smartstack_tags
node_smartstack_stack -->|"guards"| node_smartstack_termination
node_smartstack_name -->|"formats"| node_name_system
node_smartstack_tags -->|"checks"| node_feature_flags
node_smartstack_tags -->|"uses"| node_utils_find
node_smartstack_stack -->|"uses"| node_template_index
node_project_project -->|"annotates"| node_error_add
node_feature_flags -->|"controls"| node_smartstack_tags

click node_src_index "https://github.com/alma-cdk/project/blob/main/src/index.ts"
click node_src_project_index "https://github.com/alma-cdk/project/blob/main/src/project/index.ts"
click node_project_project "https://github.com/alma-cdk/project/blob/main/src/project/project.ts"
click node_project_context "https://github.com/alma-cdk/project/blob/main/src/project/project-context.ts"
click node_account_type "https://github.com/alma-cdk/project/blob/main/src/project/account-type.ts"
click node_environment_type "https://github.com/alma-cdk/project/blob/main/src/project/environment-type.ts"
click node_resolve_region "https://github.com/alma-cdk/project/blob/main/src/project/resolve-region.ts"
click node_src_context_index "https://github.com/alma-cdk/project/blob/main/src/context/index.ts"
click node_context_account "https://github.com/alma-cdk/project/blob/main/src/context/account.ts"
click node_context_environment "https://github.com/alma-cdk/project/blob/main/src/context/environment.ts"
click node_account_wrapper "https://github.com/alma-cdk/project/blob/main/src/wrapper/account.ts"
click node_environment_wrapper "https://github.com/alma-cdk/project/blob/main/src/wrapper/environment.ts"
click node_smartstack_stack "https://github.com/alma-cdk/project/blob/main/src/smartstack/stack.ts"
click node_smartstack_name "https://github.com/alma-cdk/project/blob/main/src/smartstack/name/index.ts"
click node_smartstack_tags "https://github.com/alma-cdk/project/blob/main/src/smartstack/tags/index.ts"
click node_smartstack_termination "https://github.com/alma-cdk/project/blob/main/src/smartstack/termination/index.ts"
click node_name_system "https://github.com/alma-cdk/project/blob/main/src/name/index.ts"
click node_feature_flags "https://github.com/alma-cdk/project/blob/main/src/feature-flags/index.ts"
click node_error_add "https://github.com/alma-cdk/project/blob/main/src/error/add.ts"
click node_template_index "https://github.com/alma-cdk/project/blob/main/src/template/index.ts"
click node_utils_find "https://github.com/alma-cdk/project/blob/main/src/utils/find.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_index toneBlue
class node_src_project_index,node_project_project,node_project_context,node_account_type,node_environment_type,node_resolve_region,node_src_context_index,node_context_account,node_context_environment,node_account_wrapper,node_environment_wrapper toneAmber
class node_smartstack_stack,node_smartstack_name,node_smartstack_tags,node_smartstack_termination,node_name_system,node_feature_flags toneMint
class node_error_add,node_template_index,node_utils_find toneRose
```

## Components

### Public API

Package entrypoints exported from src/index.ts and module barrels

- [Package API](https://github.com/alma-cdk/project/blob/main/src/index.ts): entrypoint · Top-level library exports for @alma-cdk/project · `src/index.ts`

### Project Runtime

Project orchestration, account/environment modeling, and deployment scope

- [Project API](https://github.com/alma-cdk/project/blob/main/src/project/index.ts): barrel · Project-related exports · `src/project/index.ts`
- [Project](https://github.com/alma-cdk/project/blob/main/src/project/project.ts): orchestrator · Root CDK scope carrying project metadata and account strategy · `src/project/project.ts`
- [Project Context](https://github.com/alma-cdk/project/blob/main/src/project/project-context.ts): context model · Typed project-wide context and metadata resolution · `src/project/project-context.ts`
- [Account Type](https://github.com/alma-cdk/project/blob/main/src/project/account-type.ts): enum logic · Account classification and strategy helpers · `src/project/account-type.ts`
- [Env Type](https://github.com/alma-cdk/project/blob/main/src/project/environment-type.ts): enum logic · Environment classification and stability helpers · `src/project/environment-type.ts`
- [Region Resolve](https://github.com/alma-cdk/project/blob/main/src/project/resolve-region.ts): region logic · Default region selection and resolution rules · `src/project/resolve-region.ts`
- [Context API](https://github.com/alma-cdk/project/blob/main/src/context/index.ts): barrel · Context resolution exports · `src/context/index.ts`
- [Account Context](https://github.com/alma-cdk/project/blob/main/src/context/account.ts): context resolver · Resolves selected account from CDK context · `src/context/account.ts`
- [Env Context](https://github.com/alma-cdk/project/blob/main/src/context/environment.ts): context resolver · Resolves selected environment from CDK context · `src/context/environment.ts`
- [Account Wrapper](https://github.com/alma-cdk/project/blob/main/src/wrapper/account.ts): scope wrapper · Account-scoped composition boundary beneath Project · `src/wrapper/account.ts`
- [Env Wrapper](https://github.com/alma-cdk/project/blob/main/src/wrapper/environment.ts): scope wrapper · Environment-scoped composition boundary beneath AccountWrapper · `src/wrapper/environment.ts`

### Stack Conventions

Smart stack abstractions, naming, tagging, and termination behavior

- [SmartStack](https://github.com/alma-cdk/project/blob/main/src/smartstack/stack.ts): stack abstraction · CDK Stack wrapper with project conventions · `src/smartstack/stack.ts`
- [Stack Names](https://github.com/alma-cdk/project/blob/main/src/smartstack/name/index.ts): naming helper · Stack-specific naming conventions · `src/smartstack/name/index.ts`
- [Stack Tags](https://github.com/alma-cdk/project/blob/main/src/smartstack/tags/index.ts): tagging subsystem · Standard tags, exclusions, and compatibility checks · `src/smartstack/tags/index.ts`
- [Termination](https://github.com/alma-cdk/project/blob/main/src/smartstack/termination/index.ts): safety helper · Termination protection behavior for stacks · `src/smartstack/termination/index.ts`
- [Name System](https://github.com/alma-cdk/project/blob/main/src/name/index.ts): naming subsystem · Name, URL, and path formatting with length trimming · `src/name/index.ts`
- [Feature Flags](https://github.com/alma-cdk/project/blob/main/src/feature-flags/index.ts): compat layer · Legacy and v0 tag compatibility switches · `src/feature-flags/index.ts`

### Support Modules

Shared helpers, error metadata, and template utilities

- [Error Metadata](https://github.com/alma-cdk/project/blob/main/src/error/add.ts): error helper · Structured error augmentation utilities · `src/error/add.ts`
- [Template Utils](https://github.com/alma-cdk/project/blob/main/src/template/index.ts): template helper · Reusable template-related helpers · `src/template/index.ts`
- [Shared Utils](https://github.com/alma-cdk/project/blob/main/src/utils/find.ts): utility helpers · General-purpose lookup and access helpers · `src/utils/find.ts`

## Connections

- Package API → Project API: exports · Package entrypoint re-exports project API
- Package API → Context API: exports · Package entrypoint re-exports context API
- Package API → SmartStack: exports · Package entrypoint exposes stack abstraction
- Package API → Name System: exports · Package entrypoint exposes naming helpers
- Package API → Feature Flags: exports · Package entrypoint exposes compatibility flags
- Package API → Error Metadata: exports · Package entrypoint exposes error helpers
- Project API → Project: builds · Project API centers on the root orchestration object
- Project API → Project Context: types · Project API exports project-wide context types
- Project → Project Context: stores · Project carries normalized project metadata
- Project → Account Type: uses · Project binds account strategy
- Project → Env Type: uses · Project binds environment behavior
- Project → Region Resolve: resolves · Project determines default region
- Context API → Account Context: exports · Context barrel exposes account resolution
- Context API → Env Context: exports · Context barrel exposes environment resolution
- Account Context → Env Context: coordinates · Account and environment selection are interpreted together from CDK context
- Account Context → Account Wrapper: binds · Resolved account becomes the account scope boundary
- Env Context → Env Wrapper: binds · Resolved environment becomes the environment scope boundary
- Project → Account Wrapper: contains · Project is the parent scope for accounts
- Account Wrapper → Env Wrapper: contains · Account scope contains one or more environments
- Env Wrapper → SmartStack: hosts · Environment scope hosts application stacks
- SmartStack → Stack Names: applies · Stacks use naming conventions for safe identifiers
- SmartStack → Stack Tags: applies · Stacks apply standard tags through centralized tagging
- SmartStack → Termination: guards · Stacks can enable termination protection rules
- Stack Names → Name System: formats · Stack names are derived from the shared naming system
- Stack Tags → Feature Flags: checks · Tag behavior depends on compatibility feature flags
- Stack Tags → Shared Utils: uses · Tag selection and exclusion logic uses shared utilities
- SmartStack → Template Utils: uses · Stack implementation relies on template helpers
- Project → Error Metadata: annotates · Project errors carry structured metadata
- Feature Flags → Stack Tags: controls · Legacy and v0 modes alter tag semantics