# Frontend shell

Active contributors: Douwe de Vries, vriesd

## Purpose

The frontend shell renders QA Scribe's desktop UI and owns interaction state. It keeps workflows in controller/action modules and keeps views focused on rendering and user events.

## Directory layout

```text
frontend/src/
  app/
  views/
  editor/
  workflows/
  components/
  styles/
```

## Key source files

| File | Purpose |
| --- | --- |
| `frontend/src/app/useAppController.ts` | Central app state, boot flow, autosave, provider state, generation jobs. |
| `frontend/src/app/AppShell.tsx` | Layout, navigation, and view selection. |
| `frontend/src/app/sessionActions.ts` | Session and note operations. |
| `frontend/src/app/recordActions.ts` | Draft and Finding record operations. |
| `frontend/src/app/generationActions.ts` | AI job start/reconcile/cancel behavior. |
| `frontend/src/app/attachmentActions.ts` | Image paste/import/materialization. |
| `frontend/src/views/SessionEditorView.tsx` | Notes editor view. |
| `frontend/src/views/TestwareView.tsx` | Testware draft collection view. |
| `frontend/src/views/FindingsView.tsx` | Findings collection view. |
| `frontend/src/editor/RichTextEditor.tsx` | TipTap editor integration. |

## How it works

`frontend/src/App.tsx` renders `AppShell` with props from `useAppController`. The controller creates an `AppWorkflowContext`, passes it into action factories, and returns state plus handlers to the shell and views.

```mermaid
graph TD
    App[App.tsx] --> Controller[useAppController]
    App --> Shell[AppShell]
    Controller --> Actions[Action factories]
    Shell --> Views[Notes, Testware, Findings, Settings]
    Views --> Actions
    Actions --> Bridge[frontend/src/tauri.ts]
```

## Integration points

The frontend shell depends on [Tauri command bridge](systems--tauri-command-bridge.md), [Rich record editing](features--rich-record-editing.md), and [AI-assisted Testware](features--ai-assisted-testware.md).

## Entry points for modification

For a new workflow, add state to `frontend/src/app/useAppController.ts`, action logic to a focused file under `frontend/src/app`, and rendering under `frontend/src/views` or `frontend/src/components`.