diff --git a/README.md b/README.md
index b8aa359..189ace0 100644
--- a/README.md
+++ b/README.md
@@ -6,8 +6,9 @@ PySentry is being designed and implemented with assistance from OpenAI Codex.
 
 Project notes:
 
-- [Changelog](CHANGELOG.md)
-- [Roadmap](ROADMAP.md)
+- [Changelog](docs/CHANGELOG.md)
+- [Roadmap](docs/ROADMAP.md)
+- [Architecture](docs/ARCHITECTURE.md)
 
 ## Features
 
@@ -313,7 +314,7 @@ HKCU\Software\Microsoft\Windows\CurrentVersion\Run\PySentry
 - `src/core` contains YAML storage, command execution, scheduling, and log cleanup.
 - `assets` contains app icons that are embedded into the application binary.
 - `scripts` contains build helpers.
-- `CHANGELOG.md` records release notes and version history.
+- `docs` contains architecture notes, the changelog, and the roadmap.
 
 Build outputs are written to `dist/`. The old local `bin/` directory is not used.
 
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
new file mode 100644
index 0000000..4b1573a
--- /dev/null
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,71 @@
+# PySentry Architecture
+
+This document shows the current component interaction model. PySentry is still a
+single desktop process: the GUI, scheduler, storage, and command runner live in
+one application and communicate through Go function calls and shared in-memory
+job state.
+
+## Component Diagram
+
+```mermaid
+flowchart LR
+    user["Desktop user"]
+    gui["src/gui\nFyne windows, tabs, dialogs"]
+    store["src/core Store\nYAML config and jobs"]
+    scheduler["src/core Scheduler\n@every and cron timing"]
+    runner["src/core Runner\nshell command execution"]
+    autostart["src/core Autostart\nWindows Run / Linux desktop startup"]
+    config["pysentry.yaml\napplication settings"]
+    jobs["jobs.yaml\njob definitions"]
+    logs["logs_dir\nper-run command output logs"]
+    shell["Platform shell\ncmd.exe /C or sh -c"]
+
+    user -->|"edits jobs, settings, runs commands"| gui
+    gui -->|"OpenStore, SaveConfig, SaveJobs"| store
+    store -->|"read/write"| config
+    store -->|"read/write"| jobs
+
+    gui -->|"Start, Pause, RunNow, RefreshSchedule"| scheduler
+    scheduler -->|"SaveJobs after state changes"| store
+    scheduler -->|"RunJob(trigger)"| runner
+    runner -->|"execute command"| shell
+    runner -->|"write stdout/stderr log"| logs
+    runner -->|"RunRecord with status, duration, log path"| scheduler
+    scheduler -->|"onChange RunRecord"| gui
+    gui -->|"display History, command output, job state"| user
+
+    gui -->|"SetAutostart, AutostartStatus"| autostart
+    autostart -->|"use executable path from resolved Paths"| config
+```
+
+## Main Flows
+
+1. Startup:
+   The executable starts `cmd/pysentry`, which calls the GUI package. The GUI
+   opens the store, loads `pysentry.yaml` and `jobs.yaml`, creates the main tabs,
+   then starts the scheduler with the loaded job slice.
+
+2. Editing settings or jobs:
+   The GUI updates the in-memory job/config state and asks `Store` to write YAML
+   back to disk. Job definitions stay in one `jobs.yaml`; runtime command output
+   is not stored there.
+
+3. Scheduled run:
+   `Scheduler` checks due jobs on a one-second ticker. When a job is due, it marks
+   the job as running, saves state, and starts `Runner` asynchronously.
+
+4. Manual run:
+   `Run now` calls the same scheduler path as scheduled execution, but the
+   resulting history record uses the `Manual` trigger.
+
+5. Command execution:
+   `Runner` executes the command through the platform shell, captures stdout and
+   stderr, writes one timestamped `.log` file, and returns a `RunRecord`.
+
+6. History update:
+   The scheduler receives the `RunRecord`, updates the matching job, saves YAML,
+   runs log cleanup, and calls the GUI callback so the `History` tab refreshes.
+
+7. Autostart:
+   The Settings tab calls the platform autostart implementation. Windows uses the
+   current user's Run registry key. Linux uses a desktop-session startup entry.
diff --git a/CHANGELOG.md b/docs/CHANGELOG.md
similarity index 100%
rename from CHANGELOG.md
rename to docs/CHANGELOG.md
diff --git a/ROADMAP.md b/docs/ROADMAP.md
similarity index 100%
rename from ROADMAP.md
rename to docs/ROADMAP.md