diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000..82fd26e
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,7 @@
+# Architecture
+
+CoaxysPanel uses a registry-driven frontend architecture. `src/lib/routes.ts` defines navigable modules, sidebar entries, permissions, command-palette targets, tool cards, and page metadata.
+
+Interactive pages are composed from focused feature components. The catch-all panel route resolves known static and dynamic hosting-control paths into functional pages, avoiding dead links while keeping implementation maintainable.
+
+Client state is limited to global UI state in Zustand: sidebar state, theme, density, favorites, recent routes, and command-palette visibility. Server-like data is loaded through TanStack Query from typed mock services.