docs(architecture): init monorepo layout

Author: tranhoangpich

README.md

@@ -664,6 +664,17 @@ Analysis complete!
 
 The design goal is to keep scanning concerns, report rendering, and AI-agent onboarding separate enough that we can keep adding rules without tangling the developer workflow around them.
 
+### Monorepo Layout (Init)
+
+We initialized a clean layout for a future backend/frontend split while keeping the current Rust crate stable:
+
+- `apps/cli` placeholder for the CLI app crate
+- `packages/core` placeholder for the Rust engine + rules crate
+- `apps/frontend` placeholder for a web UI or TUI shell
+- `editors/vscode` for the current VS Code extension
+
+See `docs/ARCHITECTURE.md` and `docs/STRUCTURE.md` for the full plan and the migration checklist.
+
 ## One-Page System Data Flow
 
 1. **Input**

apps/cli/README.md

@@ -0,0 +1,5 @@
+# verifyOS CLI (placeholder)
+
+This folder is reserved for the future CLI crate when the repo becomes a Cargo workspace.
+
+For now, the CLI lives in the repository root (`src/`).

apps/frontend/README.md

@@ -0,0 +1,5 @@
+# verifyOS Frontend (placeholder)
+
+This folder is reserved for a future web UI or TUI shell.
+
+The Rust backend remains the source of truth; frontend surfaces should consume `voc` outputs instead of duplicating rules.

docs/ARCHITECTURE.md

@@ -0,0 +1,41 @@
+# Architecture
+
+This repo is evolving into a multi-surface product: a Rust backend (scanner + engine), a CLI, and editor/front-end clients.
+
+## Target Layout (Init)
+
+```
+apps/
+  cli/            # Rust CLI entrypoint (voc)
+  frontend/       # Web UI or TUI shell (future)
+packages/
+  core/           # Rust engine + rules + report model
+editors/
+  vscode/         # VS Code extension (LSP + Action Center)
+docs/
+  ARCHITECTURE.md # This document
+  STRUCTURE.md    # Tree + ownership notes
+```
+
+## Mapping From Current Repo
+
+We keep the existing Rust crate at the repo root for stability while we bootstrap the new layout.
+
+- `src/` today is the functional core and CLI.
+- `editors/vscode/` already maps cleanly to the `editors/` area.
+- `apps/cli` and `packages/core` are created as placeholders until we are ready to split into a workspace.
+
+## Why This Split
+
+- **Backend (Rust)** remains the single source of truth for rules, evidence, and repair hints.
+- **Frontend** (web/TUI) can focus on UX without duplicating logic.
+- **Editor clients** stay thin and launch `voc lsp` so diagnostics are always consistent with CLI.
+
+## Migration Plan (When Ready)
+
+1. Create a Cargo workspace at the root.
+2. Move current `src/` into `packages/core`.
+3. Add `apps/cli` crate that depends on `packages/core`.
+4. Keep `editors/vscode` unchanged (it shells out to `voc`).
+
+This keeps CI stable and avoids breaking existing releases while we grow the product.

docs/STRUCTURE.md

@@ -0,0 +1,24 @@
+# Repository Structure
+
+```
+.
+├── apps/
+│   ├── cli/            # CLI app shell (future workspace split)
+│   └── frontend/       # Web UI or TUI shell (future)
+├── packages/
+│   └── core/           # Rust engine + rules + reports (future)
+├── editors/
+│   └── vscode/         # VS Code extension
+├── docs/
+│   ├── ARCHITECTURE.md # Design overview
+│   └── STRUCTURE.md    # This file
+├── src/                # Current Rust core + CLI (active today)
+├── tests/              # Regression tests
+└── examples/           # Fixtures
+```
+
+## Ownership Notes
+
+- `src/` is still the live backend/CLI implementation.
+- `apps/` and `packages/` are initialized to guide the eventual workspace split.
+- `editors/` is production-ready and ships the VS Code extension.

packages/core/README.md

@@ -0,0 +1,10 @@
+# verifyOS Core (placeholder)
+
+This folder is reserved for the future `verifyos-core` crate that will hold:
+
+- rules
+- parsers
+- report models
+- engine orchestration
+
+For now, these live in the root `src/` directory.