# amherryyy/flower architecture

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

- Interactive diagram: https://gitdiagram.com/amherryyy/flower
- Repository: https://github.com/amherryyy/flower

## Overview

Flower is a framework and CLI for creating, validating, and safely upgrading structured projects. The principal workflow starts with a developer invoking `flower` to inspect, initialize, adopt, or update a project; plans are validated and applied through kernel operations, with journals recording changes. Separate capabilities cover module composition, database/security controls, and workflow-based agent adapters. The README documents these product branches; sampled source confirms some kernel calls, but not every CLI dispatch or integration, so unsupported internal links are omitted.

Main entry points: [`packages/cli/src/index.ts`](https://github.com/amherryyy/flower/blob/main/packages/cli/src/index.ts) (Flower CLI), [`packages/kernel/src/module.ts`](https://github.com/amherryyy/flower/blob/main/packages/kernel/src/module.ts) (Module engine), [`packages/kernel/src/journal.ts`](https://github.com/amherryyy/flower/blob/main/packages/kernel/src/journal.ts) (Local journal), [`packages/kernel/src/adoption-application.ts`](https://github.com/amherryyy/flower/blob/main/packages/kernel/src/adoption-application.ts) (Project adoption)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI entry"]
  node_cli["Flower CLI<br/>[index.ts]"]
end

subgraph group_project["Project lifecycle"]
  node_initialization["Initialization<br/>[initialization.ts]"]
  node_adoption["Project adoption"]
  node_adoption_plan["Adoption planning<br/>[adoption-plan.ts]"]
  node_modules["Module engine<br/>[module.ts]"]
  node_module_add["Module operations<br/>[module-add.ts]"]
  node_module_disposition["Remove and eject"]
  node_updates["Update planning<br/>[update-plan.ts]"]
  node_update_apply["Update application"]
  node_release_package["Release packages<br/>[release-package.ts]"]
  node_module_auth["Auth capability<br/>[auth.ts]"]
  node_module_org["Organizations capability<br/>[organizations.ts]"]
  node_module_rbac["RBAC capability<br/>[rbac.ts]"]
  node_module_audit["Audit capability<br/>[audit.ts]"]
  node_module_limits["Limits capability<br/>[limits.ts]"]
end

subgraph group_kernel["Kernel foundations"]
  node_validation["Project validation<br/>[validation.ts]"]
  node_ownership["Ownership guards<br/>[ownership.ts]"]
  node_journal[("Local journal<br/>[journal.ts]")]
  node_templates["Template verification<br/>[template.ts]"]
end

subgraph group_controls["Database security"]
  node_migration["Database migrations"]
  node_rls["RLS controls<br/>[rls.ts]"]
  node_security["Security baseline<br/>[security.ts]"]
  node_service_role["Service-role policy<br/>[service-role.ts]"]
  node_uploads["Upload validation<br/>[upload.ts]"]
  node_usage["Usage quotas<br/>[usage-policy.ts]"]
end

subgraph group_automation["Workflow adapters"]
  node_workflow["Workflow engine<br/>[workflow.ts]"]
  node_workflow_journal[("Workflow journal")]
  node_adapter_cli["Adapter discovery<br/>[agent-adapters.ts]"]
  node_adapter_materialize["Adapter materialization"]
end

node_developer(("Developer"))

node_developer -->|"invokes"| node_cli
node_cli -->|"validates projects"| node_validation
node_cli -->|"initializes"| node_initialization
node_cli -->|"adopts projects"| node_adoption
node_cli -->|"plans updates"| node_updates
node_cli -->|"adds modules"| node_module_add
node_cli -->|"removes or ejects"| node_module_disposition
node_cli -->|"checks security"| node_security
node_cli -->|"syncs adapters"| node_adapter_cli
node_adapter_cli -->|"creates bundle"| node_adapter_materialize
node_adoption_plan -->|"resolves modules"| node_modules
node_module_add -->|"resolves modules"| node_modules
node_adoption -->|"applies plan"| node_adoption_plan
node_adoption -->|"materializes adapters"| node_adapter_materialize
node_initialization -->|"records operation"| node_journal
node_module_add -->|"records operation"| node_journal
node_adapter_materialize -->|"records operation"| node_journal
node_update_apply -->|"records operation"| node_journal
node_workflow_journal -->|"validates schema"| node_workflow
node_module_auth -.->|"defines capability"| node_modules
node_module_org -.->|"defines capability"| node_modules
node_module_rbac -.->|"defines capability"| node_modules
node_module_audit -.->|"defines capability"| node_modules
node_module_limits -.->|"defines capability"| node_modules

click node_cli "https://github.com/amherryyy/flower/blob/main/packages/cli/src/index.ts"
click node_validation "https://github.com/amherryyy/flower/blob/main/packages/kernel/src/validation.ts"
click node_ownership "https://github.com/amherryyy/flower/blob/main/packages/kernel/src/ownership.ts"
click node_journal "https://github.com/amherryyy/flower/blob/main/packages/kernel/src/journal.ts"
click node_initialization "https://github.com/amherryyy/flower/blob/main/packages/kernel/src/initialization.ts"
click node_adoption "https://github.com/amherryyy/flower/blob/main/packages/kernel/src/adoption-application.ts"
click node_adoption_plan "https://github.com/amherryyy/flower/blob/main/packages/kernel/src/adoption-plan.ts"
click node_modules "https://github.com/amherryyy/flower/blob/main/packages/kernel/src/module.ts"
click node_module_add "https://github.com/amherryyy/flower/blob/main/packages/kernel/src/module-add.ts"
click node_module_disposition "https://github.com/amherryyy/flower/blob/main/packages/kernel/src/module-disposition.ts"
click node_updates "https://github.com/amherryyy/flower/blob/main/packages/kernel/src/update-plan.ts"
click node_update_apply "https://github.com/amherryyy/flower/blob/main/packages/kernel/src/update-application.ts"
click node_templates "https://github.com/amherryyy/flower/blob/main/packages/kernel/src/template.ts"
click node_release_package "https://github.com/amherryyy/flower/blob/main/packages/kernel/src/release-package.ts"
click node_migration "https://github.com/amherryyy/flower/blob/main/packages/kernel/src/postgres-migration.ts"
click node_rls "https://github.com/amherryyy/flower/blob/main/packages/kernel/src/rls.ts"
click node_security "https://github.com/amherryyy/flower/blob/main/packages/kernel/src/security.ts"
click node_service_role "https://github.com/amherryyy/flower/blob/main/packages/kernel/src/service-role.ts"
click node_uploads "https://github.com/amherryyy/flower/blob/main/packages/kernel/src/upload.ts"
click node_usage "https://github.com/amherryyy/flower/blob/main/packages/kernel/src/usage-policy.ts"
click node_workflow "https://github.com/amherryyy/flower/blob/main/packages/kernel/src/workflow.ts"
click node_workflow_journal "https://github.com/amherryyy/flower/blob/main/packages/kernel/src/workflow-journal.ts"
click node_adapter_cli "https://github.com/amherryyy/flower/blob/main/packages/cli/src/agent-adapters.ts"
click node_adapter_materialize "https://github.com/amherryyy/flower/blob/main/packages/kernel/src/agent-adapter-materialization.ts"
click node_module_auth "https://github.com/amherryyy/flower/blob/main/modules/auth/generators/src/flower/auth.ts"
click node_module_org "https://github.com/amherryyy/flower/blob/main/modules/organizations/generators/src/flower/organizations.ts"
click node_module_rbac "https://github.com/amherryyy/flower/blob/main/modules/rbac/generators/src/flower/rbac.ts"
click node_module_audit "https://github.com/amherryyy/flower/blob/main/modules/audit/generators/src/flower/audit.ts"
click node_module_limits "https://github.com/amherryyy/flower/blob/main/modules/limits/generators/src/flower/limits.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_cli toneBlue
class node_initialization,node_adoption,node_adoption_plan,node_modules,node_module_add,node_module_disposition,node_updates,node_update_apply,node_release_package,node_module_auth,node_module_org,node_module_rbac,node_module_audit,node_module_limits toneAmber
class node_validation,node_ownership,node_journal,node_templates toneMint
class node_migration,node_rls,node_security,node_service_role,node_uploads,node_usage toneRose
class node_workflow,node_workflow_journal,node_adapter_cli,node_adapter_materialize,node_developer toneIndigo
```

## Components

### CLI entry

- [Flower CLI](https://github.com/amherryyy/flower/blob/main/packages/cli/src/index.ts): `packages/cli/src/index.ts`

### Project lifecycle

- [Initialization](https://github.com/amherryyy/flower/blob/main/packages/kernel/src/initialization.ts): `packages/kernel/src/initialization.ts`
- [Project adoption](https://github.com/amherryyy/flower/blob/main/packages/kernel/src/adoption-application.ts): `packages/kernel/src/adoption-application.ts`
- [Adoption planning](https://github.com/amherryyy/flower/blob/main/packages/kernel/src/adoption-plan.ts): `packages/kernel/src/adoption-plan.ts`
- [Module engine](https://github.com/amherryyy/flower/blob/main/packages/kernel/src/module.ts): `packages/kernel/src/module.ts`
- [Module operations](https://github.com/amherryyy/flower/blob/main/packages/kernel/src/module-add.ts): `packages/kernel/src/module-add.ts`
- [Remove and eject](https://github.com/amherryyy/flower/blob/main/packages/kernel/src/module-disposition.ts): `packages/kernel/src/module-disposition.ts`
- [Update planning](https://github.com/amherryyy/flower/blob/main/packages/kernel/src/update-plan.ts): `packages/kernel/src/update-plan.ts`
- [Update application](https://github.com/amherryyy/flower/blob/main/packages/kernel/src/update-application.ts): `packages/kernel/src/update-application.ts`
- [Release packages](https://github.com/amherryyy/flower/blob/main/packages/kernel/src/release-package.ts): `packages/kernel/src/release-package.ts`
- [Auth capability](https://github.com/amherryyy/flower/blob/main/modules/auth/generators/src/flower/auth.ts): `modules/auth/generators/src/flower/auth.ts`
- [Organizations capability](https://github.com/amherryyy/flower/blob/main/modules/organizations/generators/src/flower/organizations.ts): `modules/organizations/generators/src/flower/organizations.ts`
- [RBAC capability](https://github.com/amherryyy/flower/blob/main/modules/rbac/generators/src/flower/rbac.ts): `modules/rbac/generators/src/flower/rbac.ts`
- [Audit capability](https://github.com/amherryyy/flower/blob/main/modules/audit/generators/src/flower/audit.ts): `modules/audit/generators/src/flower/audit.ts`
- [Limits capability](https://github.com/amherryyy/flower/blob/main/modules/limits/generators/src/flower/limits.ts): `modules/limits/generators/src/flower/limits.ts`

### Kernel foundations

- [Project validation](https://github.com/amherryyy/flower/blob/main/packages/kernel/src/validation.ts): `packages/kernel/src/validation.ts`
- [Ownership guards](https://github.com/amherryyy/flower/blob/main/packages/kernel/src/ownership.ts): `packages/kernel/src/ownership.ts`
- [Local journal](https://github.com/amherryyy/flower/blob/main/packages/kernel/src/journal.ts): `packages/kernel/src/journal.ts`
- [Template verification](https://github.com/amherryyy/flower/blob/main/packages/kernel/src/template.ts): `packages/kernel/src/template.ts`

### Database security

- [Database migrations](https://github.com/amherryyy/flower/blob/main/packages/kernel/src/postgres-migration.ts): `packages/kernel/src/postgres-migration.ts`
- [RLS controls](https://github.com/amherryyy/flower/blob/main/packages/kernel/src/rls.ts): `packages/kernel/src/rls.ts`
- [Security baseline](https://github.com/amherryyy/flower/blob/main/packages/kernel/src/security.ts): `packages/kernel/src/security.ts`
- [Service-role policy](https://github.com/amherryyy/flower/blob/main/packages/kernel/src/service-role.ts): `packages/kernel/src/service-role.ts`
- [Upload validation](https://github.com/amherryyy/flower/blob/main/packages/kernel/src/upload.ts): `packages/kernel/src/upload.ts`
- [Usage quotas](https://github.com/amherryyy/flower/blob/main/packages/kernel/src/usage-policy.ts): `packages/kernel/src/usage-policy.ts`

### Workflow adapters

- [Workflow engine](https://github.com/amherryyy/flower/blob/main/packages/kernel/src/workflow.ts): `packages/kernel/src/workflow.ts`
- [Workflow journal](https://github.com/amherryyy/flower/blob/main/packages/kernel/src/workflow-journal.ts): `packages/kernel/src/workflow-journal.ts`
- [Adapter discovery](https://github.com/amherryyy/flower/blob/main/packages/cli/src/agent-adapters.ts): `packages/cli/src/agent-adapters.ts`
- [Adapter materialization](https://github.com/amherryyy/flower/blob/main/packages/kernel/src/agent-adapter-materialization.ts): `packages/kernel/src/agent-adapter-materialization.ts`

### Other components

- **Developer**

## Connections

- Developer → Flower CLI: invokes (evidence: `README.md`)
- Flower CLI → Project validation: validates projects (evidence: `README.md`)
- Flower CLI → Initialization: initializes (evidence: `README.md`)
- Flower CLI → Project adoption: adopts projects (evidence: `README.md`)
- Flower CLI → Update planning: plans updates (evidence: `README.md`)
- Flower CLI → Module operations: adds modules (evidence: `README.md`)
- Flower CLI → Remove and eject: removes or ejects (evidence: `README.md`)
- Flower CLI → Security baseline: checks security (evidence: `README.md`)
- Flower CLI → Adapter discovery: syncs adapters (evidence: `README.md`)
- Adapter discovery → Adapter materialization: creates bundle (evidence: `packages/cli/src/agent-adapters.ts`)
- Adoption planning → Module engine: resolves modules (evidence: `packages/kernel/src/adoption-plan.ts`)
- Module operations → Module engine: resolves modules (evidence: `packages/kernel/src/module-add.ts`)
- Project adoption → Adoption planning: applies plan (evidence: `packages/kernel/src/adoption-application.ts`)
- Project adoption → Adapter materialization: materializes adapters (evidence: `packages/kernel/src/adoption-application.ts`)
- Initialization → Local journal: records operation (evidence: `packages/kernel/src/initialization.ts`)
- Module operations → Local journal: records operation (evidence: `packages/kernel/src/module-add.ts`)
- Adapter materialization → Local journal: records operation (evidence: `packages/kernel/src/agent-adapter-materialization.ts`)
- Update application → Local journal: records operation (evidence: `packages/kernel/src/update-application.ts`)
- Workflow journal → Workflow engine: validates schema (evidence: `packages/kernel/src/workflow-journal.ts`)
- Auth capability → Module engine: defines capability
- Organizations capability → Module engine: defines capability
- RBAC capability → Module engine: defines capability
- Audit capability → Module engine: defines capability
- Limits capability → Module engine: defines capability
