# vizzaq23/sunny-hq architecture

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

- Interactive diagram: https://gitdiagram.com/vizzaq23/sunny-hq
- Repository: https://github.com/vizzaq23/sunny-hq
- Video tour (about a minute): https://gitdiagram.com/vizzaq23/sunny-hq/video

## Overview

Sunny HQ is a local Electron/React AI workspace for organizing projects, starting Codex missions, following conversations and tool activity, and reviewing or saving results. The main user path runs from the Home/crew interface through mission and task views to desktop IPC-backed services, then returns saved status and results for review. Other documented branches include project tools and history import, the local developer crew, and recovery/persistence. Some service wiring is unsampled, so only documented or indexed relationships are drawn; uncertain links are omitted.

Main entry points: [`src/App.tsx`](https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/App.tsx) (App shell), [`desktop/main.cjs`](https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/desktop/main.cjs) (Electron main), [`src/views/MissionBoard.tsx`](https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/views/MissionBoard.tsx) (Mission board), [`desktop/fragment-store.cjs`](https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/desktop/fragment-store.cjs) (Fragment store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Workspace UI"]
  node_renderer["Renderer entry<br/>[main.tsx]"]
  node_app["App shell<br/>[App.tsx]"]
  node_navigation["Navigation chrome<br/>[Chrome.tsx]"]
  node_home["Home and crew<br/>[DashboardViews.tsx]"]
  node_island["Crew island<br/>[IslandView.tsx]"]
  node_crew_journal["Crew journal<br/>[CrewJournal.tsx]"]
  node_deck_crew["Deck crew<br/>[DeckCrew.tsx]"]
end

subgraph group_workflow["Workflows"]
  node_crew_data["Crew catalog<br/>[data.ts]"]
  node_mission_board["Mission board<br/>[MissionBoard.tsx]"]
  node_workbench["Workbench<br/>[Workbench.tsx]"]
  node_task_flow["Task workflow<br/>[taskFlow.ts]"]
  node_mission_projection["Mission projection"]
  node_drafts["Draft state<br/>[useDraft.ts]"]
  node_transcript["Transcript state<br/>[transcriptState.ts]"]
  node_transcript_hook["Transcript hook"]
  node_work_context["Work context<br/>[workContext.ts]"]
  node_shared_types["Domain types<br/>[shared.ts]"]
end

subgraph group_desktop["Desktop services"]
  node_desktop_main["Electron main<br/>[main.cjs]"]
  node_desktop_core["Workspace core<br/>[core.cjs]"]
  node_local_crew["Local crew services<br/>[local-crew.cjs]"]
  node_codex["Codex integration<br/>[codex.cjs]"]
  node_project_tools["Project tools<br/>[catalog.cjs]"]
  node_history_import["History import<br/>[import.cjs]"]
end

subgraph group_state["Persistence"]
  node_fragment_store["Fragment store<br/>[fragment-store.cjs]"]
  node_mission_profile["Mission profile"]
  node_profile_snapshot["Profile snapshot"]
  node_copied_database["SQLite persistence"]
  node_local_data[("Local app data")]
end

node_user(("User"))

node_user -->|"opens workspace"| node_renderer
node_renderer -->|"mounts"| node_app
node_app -->|"derives work status"| node_task_flow
node_app -->|"shows workspace views"| node_home
node_app -->|"shows mission view"| node_mission_board
node_app -->|"shows workbench"| node_workbench
node_app -->|"renders navigation"| node_navigation
node_home -->|"uses crew catalog"| node_crew_data
node_home -->|"renders journal"| node_crew_journal
node_island -->|"renders crew"| node_deck_crew
node_crew_journal -->|"uses crew catalog"| node_crew_data
node_mission_board -->|"uses drafts"| node_drafts
node_mission_board -->|"checks result state"| node_work_context
node_task_flow -->|"projects mission state"| node_mission_projection
node_workbench -->|"shows conversation"| node_transcript_hook
node_transcript_hook -->|"loads transcript state"| node_transcript
node_mission_board -->|"uses domain types"| node_shared_types
node_app -.->|"requests desktop operations"| node_desktop_main
node_desktop_main -->|"loads workspace core"| node_desktop_core
node_desktop_main -->|"dispatches crew requests"| node_local_crew
node_desktop_main -.->|"starts Codex missions"| node_codex
node_desktop_main -.->|"provides project tools"| node_project_tools
node_desktop_main -.->|"imports conversations"| node_history_import
node_desktop_core -->|"uses fragment store"| node_fragment_store
node_fragment_store -->|"references snapshots"| node_profile_snapshot
node_fragment_store -->|"references profiles"| node_mission_profile
node_copied_database -->|"references store"| node_fragment_store
node_copied_database -->|"references profiles"| node_mission_profile
node_desktop_core -.->|"persists workspace data"| node_local_data
node_mission_profile -.->|"stores mission state"| node_local_data

click node_renderer "https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/main.tsx"
click node_app "https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/App.tsx"
click node_navigation "https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/components/Chrome.tsx"
click node_home "https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/views/DashboardViews.tsx"
click node_island "https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/views/IslandView.tsx"
click node_crew_journal "https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/components/CrewJournal.tsx"
click node_deck_crew "https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/components/DeckCrew.tsx"
click node_crew_data "https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/data.ts"
click node_mission_board "https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/views/MissionBoard.tsx"
click node_workbench "https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/views/Workbench.tsx"
click node_task_flow "https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/taskFlow.ts"
click node_mission_projection "https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/missionProjection.ts"
click node_drafts "https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/useDraft.ts"
click node_transcript "https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/transcriptState.ts"
click node_transcript_hook "https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/useTaskTranscript.ts"
click node_work_context "https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/workContext.ts"
click node_shared_types "https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/shared.ts"
click node_desktop_main "https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/desktop/main.cjs"
click node_desktop_core "https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/desktop/core.cjs"
click node_local_crew "https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/desktop/local-crew.cjs"
click node_codex "https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/desktop/codex.cjs"
click node_project_tools "https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/desktop/catalog.cjs"
click node_history_import "https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/desktop/import.cjs"
click node_fragment_store "https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/desktop/fragment-store.cjs"
click node_mission_profile "https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/desktop/mission-profile.cjs"
click node_profile_snapshot "https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/desktop/profile-snapshot.cjs"
click node_copied_database "https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/desktop/copied-database.cjs"

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_renderer,node_app,node_navigation,node_home,node_island,node_crew_journal,node_deck_crew,node_user toneBlue
class node_crew_data,node_mission_board,node_workbench,node_task_flow,node_mission_projection,node_drafts,node_transcript,node_transcript_hook,node_work_context,node_shared_types toneAmber
class node_desktop_main,node_desktop_core,node_local_crew,node_codex,node_project_tools,node_history_import toneMint
class node_fragment_store,node_mission_profile,node_profile_snapshot,node_copied_database,node_local_data toneRose
```

## Components

### Workspace UI

- [Renderer entry](https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/main.tsx): `src/main.tsx`
- [App shell](https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/App.tsx): `src/App.tsx`
- [Navigation chrome](https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/components/Chrome.tsx): `src/components/Chrome.tsx`
- [Home and crew](https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/views/DashboardViews.tsx): `src/views/DashboardViews.tsx`
- [Crew island](https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/views/IslandView.tsx): `src/views/IslandView.tsx`
- [Crew journal](https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/components/CrewJournal.tsx): `src/components/CrewJournal.tsx`
- [Deck crew](https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/components/DeckCrew.tsx): `src/components/DeckCrew.tsx`

### Workflows

- [Crew catalog](https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/data.ts): `src/data.ts`
- [Mission board](https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/views/MissionBoard.tsx): `src/views/MissionBoard.tsx`
- [Workbench](https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/views/Workbench.tsx): `src/views/Workbench.tsx`
- [Task workflow](https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/taskFlow.ts): `src/taskFlow.ts`
- [Mission projection](https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/missionProjection.ts): `src/missionProjection.ts`
- [Draft state](https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/useDraft.ts): `src/useDraft.ts`
- [Transcript state](https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/transcriptState.ts): `src/transcriptState.ts`
- [Transcript hook](https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/useTaskTranscript.ts): `src/useTaskTranscript.ts`
- [Work context](https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/workContext.ts): `src/workContext.ts`
- [Domain types](https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/src/shared.ts): `src/shared.ts`

### Desktop services

- [Electron main](https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/desktop/main.cjs): `desktop/main.cjs`
- [Workspace core](https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/desktop/core.cjs): `desktop/core.cjs`
- [Local crew services](https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/desktop/local-crew.cjs): `desktop/local-crew.cjs`
- [Codex integration](https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/desktop/codex.cjs): `desktop/codex.cjs`
- [Project tools](https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/desktop/catalog.cjs): `desktop/catalog.cjs`
- [History import](https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/desktop/import.cjs): `desktop/import.cjs`

### Persistence

- [Fragment store](https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/desktop/fragment-store.cjs): `desktop/fragment-store.cjs`
- [Mission profile](https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/desktop/mission-profile.cjs): `desktop/mission-profile.cjs`
- [Profile snapshot](https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/desktop/profile-snapshot.cjs): `desktop/profile-snapshot.cjs`
- [SQLite persistence](https://github.com/vizzaq23/sunny-hq/blob/codex/sunny-hq/desktop/copied-database.cjs): `desktop/copied-database.cjs`
- **Local app data**

### Other components

- **User**

## Connections

- User → Renderer entry: opens workspace (evidence: `README.md`)
- Renderer entry → App shell: mounts (evidence: `src/main.tsx`)
- App shell → Task workflow: derives work status (evidence: `src/App.tsx`)
- App shell → Home and crew: shows workspace views (evidence: `src/App.tsx`)
- App shell → Mission board: shows mission view (evidence: `src/App.tsx`)
- App shell → Workbench: shows workbench (evidence: `src/App.tsx`)
- App shell → Navigation chrome: renders navigation (evidence: `src/App.tsx`)
- Home and crew → Crew catalog: uses crew catalog (evidence: `src/views/DashboardViews.tsx`)
- Home and crew → Crew journal: renders journal (evidence: `src/views/DashboardViews.tsx`)
- Crew island → Deck crew: renders crew (evidence: `src/views/IslandView.tsx`)
- Crew journal → Crew catalog: uses crew catalog (evidence: `src/components/CrewJournal.tsx`)
- Mission board → Draft state: uses drafts (evidence: `src/views/MissionBoard.tsx`)
- Mission board → Work context: checks result state (evidence: `src/views/MissionBoard.tsx`)
- Task workflow → Mission projection: projects mission state (evidence: `src/taskFlow.ts`)
- Workbench → Transcript hook: shows conversation (evidence: `src/views/Workbench.tsx`)
- Transcript hook → Transcript state: loads transcript state (evidence: `src/useTaskTranscript.ts`)
- Mission board → Domain types: uses domain types (evidence: `src/views/MissionBoard.tsx`)
- App shell → Electron main: requests desktop operations
- Electron main → Workspace core: loads workspace core (evidence: `desktop/main.cjs`)
- Electron main → Local crew services: dispatches crew requests (evidence: `desktop/main.cjs`)
- Electron main → Codex integration: starts Codex missions (evidence: `README.md`)
- Electron main → Project tools: provides project tools (evidence: `README.md`)
- Electron main → History import: imports conversations (evidence: `README.md`)
- Workspace core → Fragment store: uses fragment store (evidence: `desktop/core.cjs`)
- Fragment store → Profile snapshot: references snapshots (evidence: `desktop/fragment-store.cjs`)
- Fragment store → Mission profile: references profiles (evidence: `desktop/fragment-store.cjs`)
- SQLite persistence → Fragment store: references store (evidence: `desktop/copied-database.cjs`)
- SQLite persistence → Mission profile: references profiles (evidence: `desktop/copied-database.cjs`)
- Workspace core → Local app data: persists workspace data (evidence: `README.md`)
- Mission profile → Local app data: stores mission state (evidence: `README.md`)