# flowtricks/stacki architecture

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

- Interactive diagram: https://gitdiagram.com/flowtricks/stacki
- Repository: https://github.com/flowtricks/stacki

## Overview

#### Purpose and Entry Points
Stacki is an Electron desktop visual editor for Astro projects. The Electron main process starts the application and mediates local-project operations; the Vite/React renderer provides the editor UI. Primary entry points are `electron/main.js`, `electron/preload.js`, `src/main.jsx`, and `src/App.jsx`.

#### Desktop Process and Privileged Boundary
The main process owns filesystem access, child-process execution, project lifecycle, Git/GitHub commands, Astro dev-server management, and app updates. The preload bridge exposes approved IPC capabilities to the renderer rather than giving UI code direct Node access. Relevant paths: `electron/main.js`, `electron/preload.js`, `electron/scaffold.js`.

#### Astro Project Model and Safe Source Editing
Astro pages are parsed into a constrained visual model: an optional layout wrapper plus a flat sequence of self-closing component instances and props. That model is serialized back to `.astro`; pages outside this grammar are routed to code editing, avoiding destructive rewrites. Astro-specific parsing and component/prop extraction are centered in `electron/astroParser.js`, with UI schema support in `src/elementSchemas.js` and `src/bindings.js`.

#### Renderer Composition and Workspace Control
`src/App.jsx` coordinates project-open/welcome state, editor selection, and the major workspace panes. `src/panels/WelcomeScreen.jsx` starts or scaffolds projects; `src/panels/PagesPanel.jsx` manages page navigation; `src/ui/PageSwitcher.jsx` provides page switching. Renderer actions cross the preload IPC boundary for reads, writes, project mutations, and process commands.

#### Visual Page Authoring Flow
Users select components from the palette, build or reorder the page structure, then edit instance props. `src/panels/PalettePanel.jsx` exposes discovered Astro components, `src/panels/StructurePanel.jsx` represents the flat page model, and `src/panels/PropsPanel.jsx` renders typed prop controls. Drag/drop state is shared through `src/dragState.js`; source updates are auto-saved and passed to Astro’s hot-reload loop.

#### Preview and Code Fallback
The app launches `astro dev` for the selected project and embeds its local output as the live preview. `src/panels/PreviewPane.jsx` is the preview surface; `src/panels/CanvasView.jsx` supports visual canvas interaction. Complex or unsupported pages use the code-editor path rather than the structural editor, through `src/ui/CodeEditor.jsx` and `src/ui/CodeWindow.jsx`.

#### Styling, Assets, and CMS Editing
The Style panel is a substantial CSS authoring subsystem, mapping selected elements to style sections, cascading/resolved values, and native-style output. Its main boundary is `src/panels/StylePanel.jsx` / `src/style-panel/index.tsx`, with CSS resolution logic in `src/style-panel/lib/cascade.ts` and `src/style-panel/lib/resolved.ts`. Asset selection is handled by `src/panels/AssetsPanel.jsx` and `src/assetPick.js`; CMS schema/reference workflows use `src/panels/CmsPanel.jsx`, `src/cmsSchema.js`, and `electron/cmsRefs.js`.

#### External Runtime and Delivery
Runtime dependencies are Node.js/npm, an opened Astro project’s `astro dev` server, local Git, and optionally authenticated GitHub CLI for publishing. Git UI is represented by `src/panels/GitChip.jsx`; command execution remains in Electron. Packaging targets macOS and Windows, with signed release automation in `.github/workflows/release.yml`, macOS entitlements under `resources/`, and Electron auto-update publication configured through `package.json`.

Main entry points: [`electron/main.js`](https://github.com/flowtricks/stacki/blob/main/electron/main.js) (Electron main process), [`src/App.jsx`](https://github.com/flowtricks/stacki/blob/main/src/App.jsx) (Workspace controller), [`src/panels/StructurePanel.jsx`](https://github.com/flowtricks/stacki/blob/main/src/panels/StructurePanel.jsx) (Visual page editor), [`electron/preload.js`](https://github.com/flowtricks/stacki/blob/main/electron/preload.js) (Preload IPC bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Electron Desktop"]
  node_main{{"Electron main process<br/>privileged host<br/>[main.js]"}}
  node_preload["Preload IPC bridge<br/>capability bridge<br/>[preload.js]"]
  node_scaffold["Project scaffolder<br/>project lifecycle<br/>[scaffold.js]"]
  node_astro_parser["Astro parser<br/>safe source model<br/>[astroParser.js]"]
  node_cms_refs["CMS references<br/>CMS backend<br/>[cmsRefs.js]"]
end

subgraph group_renderer["Renderer Workspace"]
  node_app{{"Workspace controller<br/>React application<br/>[App.jsx]"}}
  node_renderer_entry["Renderer entry<br/>Vite entry<br/>[main.jsx]"]
  node_project_navigation["Welcome and pages<br/>project navigation<br/>[PagesPanel.jsx]"]
end

subgraph group_authoring["Authoring Subsystems"]
  node_visual_editor["Visual page editor<br/>structural authoring<br/>[StructurePanel.jsx]"]
  node_ui_schema["Component schemas<br/>editor schema<br/>[elementSchemas.js]"]
  node_preview["Preview canvas<br/>live preview<br/>[PreviewPane.jsx]"]
  node_code_editor["Code fallback editor<br/>source editing<br/>[CodeEditor.jsx]"]
  node_style_panel["Style authoring<br/>CSS subsystem<br/>[index.tsx]"]
  node_assets["Asset picker<br/>asset workflow<br/>[AssetsPanel.jsx]"]
  node_cms["CMS editor<br/>CMS workflow<br/>[CmsPanel.jsx]"]
end

subgraph group_external["Project Runtime"]
  node_astro_project[("Opened Astro project<br/>local project")]
  node_astro_dev["Astro dev server<br/>local server"]
  node_git_github["Git and GitHub CLI<br/>publishing tools"]
end

subgraph group_delivery["Release Delivery"]
  node_release["Signed release automation<br/>packaging pipeline<br/>[release.yml]"]
end

node_renderer_entry -->|"mounts"| node_app
node_app -->|"uses IPC"| node_preload
node_preload -->|"approved calls"| node_main
node_main -->|"creates projects"| node_scaffold
node_main -->|"reads and serializes pages"| node_astro_parser
node_main -->|"updates references"| node_cms_refs
node_main -->|"reads and writes"| node_astro_project
node_main -->|"starts and manages"| node_astro_dev
node_main -->|"runs commands"| node_git_github
node_app -->|"hosts"| node_project_navigation
node_app -->|"hosts"| node_visual_editor
node_app -->|"hosts"| node_preview
node_app -.->|"routes unsupported pages"| node_code_editor
node_visual_editor -->|"uses schemas"| node_ui_schema
node_visual_editor -->|"edits safe model"| node_astro_parser
node_style_panel -->|"writes CSS"| node_astro_project
node_assets -->|"selects local assets"| node_astro_project
node_cms -->|"manages schema references"| node_cms_refs
node_preview -->|"embeds output"| node_astro_dev
node_astro_dev -->|"serves and watches"| node_astro_project
node_release -->|"packages desktop app"| node_main

click node_main "https://github.com/flowtricks/stacki/blob/main/electron/main.js"
click node_preload "https://github.com/flowtricks/stacki/blob/main/electron/preload.js"
click node_scaffold "https://github.com/flowtricks/stacki/blob/main/electron/scaffold.js"
click node_astro_parser "https://github.com/flowtricks/stacki/blob/main/electron/astroParser.js"
click node_cms_refs "https://github.com/flowtricks/stacki/blob/main/electron/cmsRefs.js"
click node_app "https://github.com/flowtricks/stacki/blob/main/src/App.jsx"
click node_renderer_entry "https://github.com/flowtricks/stacki/blob/main/src/main.jsx"
click node_project_navigation "https://github.com/flowtricks/stacki/blob/main/src/panels/PagesPanel.jsx"
click node_visual_editor "https://github.com/flowtricks/stacki/blob/main/src/panels/StructurePanel.jsx"
click node_ui_schema "https://github.com/flowtricks/stacki/blob/main/src/elementSchemas.js"
click node_preview "https://github.com/flowtricks/stacki/blob/main/src/panels/PreviewPane.jsx"
click node_code_editor "https://github.com/flowtricks/stacki/blob/main/src/ui/CodeEditor.jsx"
click node_style_panel "https://github.com/flowtricks/stacki/blob/main/src/style-panel/index.tsx"
click node_assets "https://github.com/flowtricks/stacki/blob/main/src/panels/AssetsPanel.jsx"
click node_cms "https://github.com/flowtricks/stacki/blob/main/src/panels/CmsPanel.jsx"
click node_release "https://github.com/flowtricks/stacki/blob/main/.github/workflows/release.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_preload,node_scaffold,node_astro_parser,node_cms_refs toneBlue
class node_app,node_renderer_entry,node_project_navigation toneAmber
class node_visual_editor,node_ui_schema,node_preview,node_code_editor,node_style_panel,node_assets,node_cms toneMint
class node_astro_project,node_astro_dev,node_git_github toneRose
class node_release toneIndigo
```

## Components

### Electron Desktop

- [Electron main process](https://github.com/flowtricks/stacki/blob/main/electron/main.js): privileged host · Owns project operations, commands, dev server, and updates. · `electron/main.js`
- [Preload IPC bridge](https://github.com/flowtricks/stacki/blob/main/electron/preload.js): capability bridge · Exposes approved renderer capabilities. · `electron/preload.js`
- [Project scaffolder](https://github.com/flowtricks/stacki/blob/main/electron/scaffold.js): project lifecycle · `electron/scaffold.js`
- [Astro parser](https://github.com/flowtricks/stacki/blob/main/electron/astroParser.js): safe source model · Parses only the supported layout and flat-component grammar. · `electron/astroParser.js`
- [CMS references](https://github.com/flowtricks/stacki/blob/main/electron/cmsRefs.js): CMS backend · `electron/cmsRefs.js`

### Renderer Workspace

- [Workspace controller](https://github.com/flowtricks/stacki/blob/main/src/App.jsx): React application · Coordinates project state, editor selection, and panes. · `src/App.jsx`
- [Renderer entry](https://github.com/flowtricks/stacki/blob/main/src/main.jsx): Vite entry · `src/main.jsx`
- [Welcome and pages](https://github.com/flowtricks/stacki/blob/main/src/panels/PagesPanel.jsx): project navigation · Opens, scaffolds, navigates, and switches pages. · `src/panels/PagesPanel.jsx`

### Authoring Subsystems

- [Visual page editor](https://github.com/flowtricks/stacki/blob/main/src/panels/StructurePanel.jsx): structural authoring · Palette, flat structure, typed props, and shared drag state. · `src/panels/StructurePanel.jsx`
- [Component schemas](https://github.com/flowtricks/stacki/blob/main/src/elementSchemas.js): editor schema · Supplies prop and binding UI definitions. · `src/elementSchemas.js`
- [Preview canvas](https://github.com/flowtricks/stacki/blob/main/src/panels/PreviewPane.jsx): live preview · Embeds local output and supports canvas interaction. · `src/panels/PreviewPane.jsx`
- [Code fallback editor](https://github.com/flowtricks/stacki/blob/main/src/ui/CodeEditor.jsx): source editing · Handles pages outside the safe visual grammar. · `src/ui/CodeEditor.jsx`
- [Style authoring](https://github.com/flowtricks/stacki/blob/main/src/style-panel/index.tsx): CSS subsystem · Resolves cascading styles and emits native CSS. · `src/style-panel/index.tsx`
- [Asset picker](https://github.com/flowtricks/stacki/blob/main/src/panels/AssetsPanel.jsx): asset workflow · `src/panels/AssetsPanel.jsx`
- [CMS editor](https://github.com/flowtricks/stacki/blob/main/src/panels/CmsPanel.jsx): CMS workflow · `src/panels/CmsPanel.jsx`

### Project Runtime

- **Opened Astro project**: local project · Contains Astro pages, components, assets, and CMS content.
- **Astro dev server**: local server · Builds and hot-reloads the selected project.
- **Git and GitHub CLI**: publishing tools · Used for local Git actions and optional GitHub publishing.

### Release Delivery

- [Signed release automation](https://github.com/flowtricks/stacki/blob/main/.github/workflows/release.yml): packaging pipeline · Packages macOS and Windows builds with auto-update publication. · `.github/workflows/release.yml`

## Connections

- Renderer entry → Workspace controller: mounts
- Workspace controller → Preload IPC bridge: uses IPC
- Preload IPC bridge → Electron main process: approved calls
- Electron main process → Project scaffolder: creates projects
- Electron main process → Astro parser: reads and serializes pages
- Electron main process → CMS references: updates references
- Electron main process → Opened Astro project: reads and writes
- Electron main process → Astro dev server: starts and manages
- Electron main process → Git and GitHub CLI: runs commands
- Workspace controller → Welcome and pages: hosts
- Workspace controller → Visual page editor: hosts
- Workspace controller → Preview canvas: hosts
- Workspace controller → Code fallback editor: routes unsupported pages
- Visual page editor → Component schemas: uses schemas
- Visual page editor → Astro parser: edits safe model
- Style authoring → Opened Astro project: writes CSS
- Asset picker → Opened Astro project: selects local assets
- CMS editor → CMS references: manages schema references
- Preview canvas → Astro dev server: embeds output
- Astro dev server → Opened Astro project: serves and watches
- Signed release automation → Electron main process: packages desktop app