alma-cdk/project

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.