wiseclaw/docs/architecture.md

WiseClaw Architecture

Core shape

WiseClaw uses a single FastAPI process with modular tool adapters:

• telegram: inbound/outbound bot handling and whitelist checks
• llm: LM Studio/OpenAI-compatible client and simple tool-routing planner
• tools: search, notes, files, terminal, and fetch tools
• memory: SQLite-backed short-term and long-term state
• admin: REST API for settings, logs, users, and health

Security defaults

• Admin panel is localhost-only by default.
• Secrets are modeled separately from normal settings so they can move to Keychain cleanly.
• Terminal mode 3 is policy based:
  • safe read-only commands auto-run
  • mutating or networked commands require approval
  • dangerous commands are blocked

Next implementation milestones

1. Add SQLAlchemy models and Alembic migrations.
2. Replace placeholder services with real SQLite persistence.
3. Wire Telegram webhook or polling loop.
4. Add LM Studio-driven tool calling.
5. Persist secrets in macOS Keychain.
6. Build audit views and approval flows in the admin panel.