# same7ammar/kube-composer architecture

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

- Interactive diagram: https://gitdiagram.com/same7ammar/kube-composer
- Repository: https://github.com/same7ammar/kube-composer

## Overview

1. **High-level shape**
   - This is a **single-page React + TypeScript application** built with **Vite** and styled with **Tailwind CSS**.
   - Its core purpose is to let a user model Kubernetes resources in the browser and generate downloadable YAML, without any backend service in the normal request path.

2. **Primary user-facing boundary**
   - `src/App.tsx` is the orchestration layer that wires the main editors, previews, summaries, and tabs together.
   - The app is organized as a set of resource-specific editors rather than a generic form engine, which keeps Kubernetes concepts explicit in the UI and the output.

3. **Resource configuration subsystem**
   - `src/components/*Manager.tsx` and `*Form.tsx` components are the main input surface for Kubernetes objects such as:
     - Deployments, DaemonSets, Jobs/CronJobs
     - Namespaces, ConfigMaps, Secrets
     - ServiceAccounts, Roles, RoleBindings, ClusterRoles
   - List components like `DeploymentsList.tsx`, `SecretsList.tsx`, and `RolesList.tsx` act as browsing/editing companions for the current project state.

4. **Kubernetes domain modeling**
   - `src/types/index.ts` defines the shared TypeScript shapes used by the editors and generators.
   - `src/data/kubernetesRBAC.ts` contains domain data for RBAC-related objects, supporting the role/permission wizard and resource generation flows.
   - This means the app’s “source of truth” is typed client-side state, not server-side persistence.

5. **Generation pipeline**
   - `src/utils/yamlGenerator.ts` is the central transformation layer that turns the in-memory Kubernetes configuration into YAML output.
   - The generated YAML is then consumed by preview/export components such as `YamlPreview.tsx`.
   - The architecture is therefore: **form state → typed config model → YAML generator → preview/export**.

6. **Visualization and feedback loop**
   - `VisualPreview.tsx` and `ResourceSummary.tsx` provide immediate feedback on the current configuration, likely showing relationships between resources and validation-like summaries.
   - `KubernetesIcons.tsx` supports a more diagrammatic presentation of resource types.
   - The app is designed to help users understand resource topology, not just produce text.

7. **Cross-cutting UI services**
   - `src/context/ThemeContext.tsx`, `src/provider/ThemeProvider.tsx`, and hooks like `useTheme.ts` / `useDarkMode.ts` manage presentation state independent of Kubernetes configuration.
   - `useUsageCounter.ts` and `src/utils/localStorage.ts` indicate browser-local persistence for usage tracking or preferences.
   - These are client-side concerns and do not affect YAML semantics.

8. **Content, SEO, and sharing layer**
   - `SEOHead.tsx`, `SocialShare.tsx`, `Footer.tsx`, `UsageCounter.tsx`, and `YouTubePopup.tsx` are supporting components for discoverability, onboarding, and engagement.
   - They sit outside the core generator path and do not participate in configuration generation, but they are part of the deployed frontend experience.

9. **Job-related subsystem**
   - `src/components/jobs/JobList.tsx` and `CronJobList.tsx`, together with `src/utils/jobsApi.ts`, suggest a dedicated area for job-oriented resource handling.
   - This appears to be a specialized sub-flow within the same browser app, not a separate service boundary.

10. **Runtime and deployment model**
   - The app is statically built and served from `dist` using **GitHub Pages** and also packaged in **Docker** for local or containerized hosting.
   - Files like `public/CNAME`, `public/.nojekyll`, and the GitHub Actions workflow under `.github/workflows/docker-build.yml` show that deployment is a build-and-publish pipeline, not an application server.
   - The Dockerfile and README’s Docker commands confirm a simple static-runtime distribution.

11. **Static asset and hosting boundary**
   - `public/` contains the site manifest, robots/sitemap files, and domain configuration, which means the repo also owns its public-facing hosting metadata.
   - `index.html`, `main.tsx`, and `index.css` form the app entry chain that bootstraps the SPA in the browser.

12. **What an architecture diagram should emphasize**
   - Draw the app as a **browser-only Kubernetes configuration studio** with:
     - input editors for resource types,
     - shared typed state,
     - a central YAML generation utility,
     - preview/summary/visualization outputs,
     - and optional local persistence/theme/usage services.
   - Outside the browser, the only material infrastructure is the **static hosting/build pipeline** via Vite, Docker, and GitHub Pages.

Main entry points: [`src/App.tsx`](https://github.com/same7ammar/kube-composer/blob/main/src/App.tsx) (App Shell), [`src/types/index.ts`](https://github.com/same7ammar/kube-composer/blob/main/src/types/index.ts) (Typed Model), [`src/components/RoleWizardManager.tsx`](https://github.com/same7ammar/kube-composer/blob/main/src/components/RoleWizardManager.tsx) (RBAC Wizard), [`src/utils/yamlGenerator.ts`](https://github.com/same7ammar/kube-composer/blob/main/src/utils/yamlGenerator.ts) (YAML Generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser App"]
  node_main(("SPA Entry<br/>bootstrap<br/>[main.tsx]"))
  node_app["App Shell<br/>orchestrator<br/>[App.tsx]"]
  node_deployment_form["Deployment Form<br/>resource editor<br/>[DeploymentForm.tsx]"]
  node_workload_forms["Workload Editors<br/>resource editors<br/>[DaemonSetForm.tsx]"]
  node_resource_managers["Resource Managers"]
  node_resource_lists["Resource Lists<br/>browser panes"]
  node_role_wizard["RBAC Wizard<br/>guided editor"]
  node_typed_state[("Typed Model<br/>shared types<br/>[index.ts]")]
  node_rbac_data["RBAC Data<br/>domain data<br/>[kubernetesRBAC.ts]"]
  node_yaml_gen{{"YAML Generator<br/>transform<br/>[yamlGenerator.ts]"}}
  node_yaml_preview["YAML Preview<br/>output view<br/>[YamlPreview.tsx]"]
  node_visual_preview["Visual Preview<br/>topology view<br/>[VisualPreview.tsx]"]
  node_summary["Resource Summary<br/>overview panel"]
end

subgraph group_platform["Platform"]
  node_static_entry["Static Shell<br/>html entry<br/>[index.html]"]
  node_hosting["Public Assets<br/>static hosting<br/>[site.webmanifest]"]
  node_build{{"Build Stack<br/>tooling<br/>[vite.config.ts]"}}
  node_deploy{{"Deploy Pipeline<br/>ci/cd<br/>[docker-build.yml]"}}
end

subgraph group_support["Support UI"]
  node_theme(("Theme Layer<br/>ui state<br/>[ThemeContext.tsx]"))
  node_persistence[("Local State<br/>browser storage<br/>[localStorage.ts]")]
  node_usage["Usage Counter<br/>engagement<br/>[UsageCounter.tsx]"]
  node_seo_share["SEO & Share<br/>marketing ui<br/>[SEOHead.tsx]"]
  node_media_ui["Media Popups<br/>engagement ui<br/>[YouTubePopup.tsx]"]
end

node_main -->|"mounts"| node_app
node_static_entry -->|"loads"| node_main
node_app -->|"wires"| node_deployment_form
node_app -->|"wires"| node_workload_forms
node_app -->|"wires"| node_resource_managers
node_app -->|"wires"| node_resource_lists
node_app -->|"wires"| node_role_wizard
node_app -->|"shows"| node_yaml_preview
node_app -->|"shows"| node_visual_preview
node_app -->|"shows"| node_summary
node_deployment_form -->|"updates"| node_typed_state
node_workload_forms -->|"updates"| node_typed_state
node_resource_managers -->|"updates"| node_typed_state
node_resource_lists -->|"reads"| node_typed_state
node_role_wizard -->|"uses"| node_rbac_data
node_role_wizard -->|"writes"| node_typed_state
node_typed_state -->|"feeds"| node_yaml_gen
node_rbac_data -->|"informs"| node_yaml_gen
node_yaml_gen -->|"renders"| node_yaml_preview
node_typed_state -->|"drives"| node_visual_preview
node_typed_state -->|"drives"| node_summary
node_theme -->|"themes"| node_app
node_persistence -->|"stores"| node_usage
node_seo_share -->|"annotates"| node_static_entry
node_media_ui -->|"supports"| node_app
node_build -->|"builds"| node_static_entry
node_deploy -->|"packages"| node_build
node_hosting -->|"served by"| node_deploy

click node_main "https://github.com/same7ammar/kube-composer/blob/main/src/main.tsx"
click node_app "https://github.com/same7ammar/kube-composer/blob/main/src/App.tsx"
click node_deployment_form "https://github.com/same7ammar/kube-composer/blob/main/src/components/DeploymentForm.tsx"
click node_workload_forms "https://github.com/same7ammar/kube-composer/blob/main/src/components/DaemonSetForm.tsx"
click node_resource_managers "https://github.com/same7ammar/kube-composer/blob/main/src/components/NamespaceManager.tsx"
click node_resource_lists "https://github.com/same7ammar/kube-composer/blob/main/src/components/DeploymentsList.tsx"
click node_role_wizard "https://github.com/same7ammar/kube-composer/blob/main/src/components/RoleWizardManager.tsx"
click node_typed_state "https://github.com/same7ammar/kube-composer/blob/main/src/types/index.ts"
click node_rbac_data "https://github.com/same7ammar/kube-composer/blob/main/src/data/kubernetesRBAC.ts"
click node_yaml_gen "https://github.com/same7ammar/kube-composer/blob/main/src/utils/yamlGenerator.ts"
click node_yaml_preview "https://github.com/same7ammar/kube-composer/blob/main/src/components/YamlPreview.tsx"
click node_visual_preview "https://github.com/same7ammar/kube-composer/blob/main/src/components/VisualPreview.tsx"
click node_summary "https://github.com/same7ammar/kube-composer/blob/main/src/components/ResourceSummary.tsx"
click node_theme "https://github.com/same7ammar/kube-composer/blob/main/src/context/ThemeContext.tsx"
click node_persistence "https://github.com/same7ammar/kube-composer/blob/main/src/utils/localStorage.ts"
click node_usage "https://github.com/same7ammar/kube-composer/blob/main/src/components/UsageCounter.tsx"
click node_seo_share "https://github.com/same7ammar/kube-composer/blob/main/src/components/SEOHead.tsx"
click node_media_ui "https://github.com/same7ammar/kube-composer/blob/main/src/components/YouTubePopup.tsx"
click node_static_entry "https://github.com/same7ammar/kube-composer/blob/main/index.html"
click node_hosting "https://github.com/same7ammar/kube-composer/blob/main/public/site.webmanifest"
click node_build "https://github.com/same7ammar/kube-composer/blob/main/vite.config.ts"
click node_deploy "https://github.com/same7ammar/kube-composer/blob/main/.github/workflows/docker-build.yml"

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_main,node_app,node_deployment_form,node_workload_forms,node_resource_managers,node_resource_lists,node_role_wizard,node_typed_state,node_rbac_data,node_yaml_gen,node_yaml_preview,node_visual_preview,node_summary toneBlue
class node_static_entry,node_hosting,node_build,node_deploy toneAmber
class node_theme,node_persistence,node_usage,node_seo_share,node_media_ui toneMint
```

## Components

### Browser App

Client-side Kubernetes configuration studio and its in-browser data flow.

- [SPA Entry](https://github.com/same7ammar/kube-composer/blob/main/src/main.tsx): bootstrap · Browser entry that mounts the application. · `src/main.tsx`
- [App Shell](https://github.com/same7ammar/kube-composer/blob/main/src/App.tsx): orchestrator · Top-level composition and state wiring for the studio. · `src/App.tsx`
- [Deployment Form](https://github.com/same7ammar/kube-composer/blob/main/src/components/DeploymentForm.tsx): resource editor · Editor for Deployment configuration. · `src/components/DeploymentForm.tsx`
- [Workload Editors](https://github.com/same7ammar/kube-composer/blob/main/src/components/DaemonSetForm.tsx): resource editors · DaemonSet and Job editing surfaces. · `src/components/DaemonSetForm.tsx`
- [Resource Managers](https://github.com/same7ammar/kube-composer/blob/main/src/components/NamespaceManager.tsx): resource managers · Editors for core Kubernetes objects like namespaces, configmaps, secrets, and RBAC. · `src/components/NamespaceManager.tsx`
- [Resource Lists](https://github.com/same7ammar/kube-composer/blob/main/src/components/DeploymentsList.tsx): browser panes · Companion lists for browsing and editing current project resources. · `src/components/DeploymentsList.tsx`
- [RBAC Wizard](https://github.com/same7ammar/kube-composer/blob/main/src/components/RoleWizardManager.tsx): guided editor · Role and permission flow built on domain RBAC data. · `src/components/RoleWizardManager.tsx`
- [Typed Model](https://github.com/same7ammar/kube-composer/blob/main/src/types/index.ts): shared types · Client-side source of truth for Kubernetes configuration. · `src/types/index.ts`
- [RBAC Data](https://github.com/same7ammar/kube-composer/blob/main/src/data/kubernetesRBAC.ts): domain data · Static RBAC knowledge used by the wizard and generators. · `src/data/kubernetesRBAC.ts`
- [YAML Generator](https://github.com/same7ammar/kube-composer/blob/main/src/utils/yamlGenerator.ts): transform · Converts typed configuration state into YAML output. · `src/utils/yamlGenerator.ts`
- [YAML Preview](https://github.com/same7ammar/kube-composer/blob/main/src/components/YamlPreview.tsx): output view · Rendered YAML inspection and export surface. · `src/components/YamlPreview.tsx`
- [Visual Preview](https://github.com/same7ammar/kube-composer/blob/main/src/components/VisualPreview.tsx): topology view · Diagrammatic view of configured Kubernetes resources. · `src/components/VisualPreview.tsx`
- [Resource Summary](https://github.com/same7ammar/kube-composer/blob/main/src/components/ResourceSummary.tsx): overview panel · Condensed configuration and relationship summary. · `src/components/ResourceSummary.tsx`

### Platform

Build, static hosting, and packaging layers around the SPA.

- [Static Shell](https://github.com/same7ammar/kube-composer/blob/main/index.html): html entry · Vite-served HTML host for the SPA. · `index.html`
- [Public Assets](https://github.com/same7ammar/kube-composer/blob/main/public/site.webmanifest): static hosting · Manifest, robots, sitemap, and domain metadata. · `public/site.webmanifest`
- [Build Stack](https://github.com/same7ammar/kube-composer/blob/main/vite.config.ts): tooling · Vite, Tailwind, and package-based frontend build pipeline. · `vite.config.ts`
- [Deploy Pipeline](https://github.com/same7ammar/kube-composer/blob/main/.github/workflows/docker-build.yml): ci/cd · Docker and GitHub Actions build-and-publish path. · `.github/workflows/docker-build.yml`

### Support UI

Non-core UI services and engagement components.

- [Theme Layer](https://github.com/same7ammar/kube-composer/blob/main/src/context/ThemeContext.tsx): ui state · Theme and dark-mode presentation state. · `src/context/ThemeContext.tsx`
- [Local State](https://github.com/same7ammar/kube-composer/blob/main/src/utils/localStorage.ts): browser storage · Usage counters and persisted UI preferences. · `src/utils/localStorage.ts`
- [Usage Counter](https://github.com/same7ammar/kube-composer/blob/main/src/components/UsageCounter.tsx): engagement · Browser-side usage tracking component. · `src/components/UsageCounter.tsx`
- [SEO & Share](https://github.com/same7ammar/kube-composer/blob/main/src/components/SEOHead.tsx): marketing ui · Head metadata and social sharing controls. · `src/components/SEOHead.tsx`
- [Media Popups](https://github.com/same7ammar/kube-composer/blob/main/src/components/YouTubePopup.tsx): engagement ui · Onboarding and promo overlays. · `src/components/YouTubePopup.tsx`

## Connections

- SPA Entry → App Shell: mounts · Bootstraps the application shell.
- Static Shell → SPA Entry: loads · HTML entry loads the SPA bundle.
- App Shell → Deployment Form: wires · Composes the deployment editor into the shell.
- App Shell → Workload Editors: wires · Includes workload-specific editing flows.
- App Shell → Resource Managers: wires · Connects core Kubernetes resource editors.
- App Shell → Resource Lists: wires · Provides list and navigation panes.
- App Shell → RBAC Wizard: wires · Includes the RBAC setup wizard.
- App Shell → YAML Preview: shows · Exposes generated YAML to the user.
- App Shell → Visual Preview: shows · Displays the resource topology view.
- App Shell → Resource Summary: shows · Presents a compact state summary.
- Deployment Form → Typed Model: updates · Edits the shared configuration model.
- Workload Editors → Typed Model: updates · Edits the shared configuration model.
- Resource Managers → Typed Model: updates · Mutates the client-side Kubernetes state.
- Resource Lists → Typed Model: reads · Browses the current typed project state.
- RBAC Wizard → RBAC Data: uses · Uses RBAC domain rules and options.
- RBAC Wizard → Typed Model: writes · Stores wizard output in the shared model.
- Typed Model → YAML Generator: feeds · Primary input to YAML generation.
- RBAC Data → YAML Generator: informs · Supplies RBAC-specific generation knowledge.
- YAML Generator → YAML Preview: renders · Generated YAML is shown in preview/export.
- Typed Model → Visual Preview: drives · Resource model powers diagrammatic preview.
- Typed Model → Resource Summary: drives · Current model powers the summary panel.
- Theme Layer → App Shell: themes · Provides presentation state across the app.
- Local State → Usage Counter: stores · Persists usage and preference data locally.
- SEO & Share → Static Shell: annotates · Adds metadata and sharing hooks to the site shell.
- Media Popups → App Shell: supports · Auxiliary engagement and onboarding surfaces.
- Build Stack → Static Shell: builds · Frontend tooling produces the browser bundle.
- Deploy Pipeline → Build Stack: packages · CI and Docker run the production build.
- Public Assets → Deploy Pipeline: served by · Public static assets ship with the deployed site.
