# ClaudeTools — Mission & Product Direction

## Mission

ClaudeTools is the internal operations platform for Arizona Computer Guru LLC. It tracks client work, billable time, infrastructure inventory, and encrypted credentials — and it provides a real-time coordination layer so that multiple Claude Code sessions (running on different machines or by different team members) can work in parallel without stepping on each other. It is built to support a 2-person MSP that uses AI-assisted workflows as a core part of how work gets done.

---

## Target User

**Primary:** Mike Swanson and Howard Enos — the two team members at Arizona Computer Guru LLC. They use Claude Code sessions throughout the day to handle client work, MSP tooling development, and infrastructure operations. ClaudeTools gives those sessions a shared source of truth.

**Claude Code sessions themselves** are also first-class consumers of the API — particularly the coordination subsystem, which sessions query at startup and before writing to any shared resource.

There is no external user base. This is internal infrastructure.

---

## Current Scope (what it does today)

**Work tracking:**
- Client management (`/api/clients`)
- Project tracking (`/api/projects`)
- Work session logging (`/api/sessions`)
- Billable time entries with rate and amount (`/api/billable-time`)
- Work items and task management (`/api/work-items`, `/api/tasks`)
- Tagging system across entities (`/api/tags`)

**Infrastructure inventory:**
- Machine inventory (`/api/machines`)
- Physical sites (`/api/sites`)
- IT assets/infrastructure (`/api/infrastructure`)
- Application services (`/api/services`)
- Network configurations (`/api/networks`)
- Firewall rule documentation (`/api/firewall-rules`)
- M365 tenant records (`/api/m365-tenants`)

**Credential management:**
- Encrypted credential storage (AES-256-GCM) for client and service credentials (`/api/credentials`)
- Immutable audit log of all credential access (`/api/credential-audit-logs`)
- Security incident tracking (`/api/security-incidents`)

**Authentication:**
- JWT-based auth with Argon2 password hashing (`/api/auth/token`)

**Coordination subsystem (`/api/coord`):**
- Component state tracking per project (GuruRMM, ClaudeTools, Dataforth, client work)
- Work locks: sessions claim a lock on a resource before writing; TTL-based auto-release
- Inter-session messaging: one Claude session can leave a note for another (e.g., "I left the server mid-deploy")
- No auth required — internal LAN only

**MCP integration:**
- `mcp-servers/feature-management/` — GuruRMM feature request tracking, accessible from Claude Code via MCP

---

## Near-Term Roadmap

- Auto-deploy via Gitea webhook (planned, not yet active)
- Optional Phase 7 extensions (all low-priority):
  - File Changes API — track file modifications over time
  - Command Runs API — command execution history
  - Problem Solutions API — internal knowledge base
  - Failure Patterns API — error pattern recognition
  - Environmental Insights API — contextual learning across sessions

The API is considered feature-complete for current operational needs. New endpoints are added only when a specific workflow gap appears.

---

## Explicit Non-Goals

- **Not a PSA replacement** — ClaudeTools tracks work for internal record-keeping. Syncro PSA handles client-facing ticketing and invoicing; the two are separate.
- **Not a multi-tenant SaaS product** — single-tenant, self-hosted on ACG infrastructure. No plans to expose this to external users or clients.
- **Not a monitoring platform** — GuruRMM handles endpoint monitoring. ClaudeTools tracks the work done in response to what monitoring surfaces.
- **No external credential access UI** — credentials stored in ClaudeTools are accessed via API by Claude Code sessions. There is no web UI for browsing credentials.
- **No hardcoded credentials anywhere** — all secrets go through SOPS vault (primary) or 1Password (fallback). This is a non-negotiable constraint, not a goal to eventually achieve.

---

## Design Principles

**Coordination is first-class** — the coord API is not an afterthought. Multi-session, multi-machine Claude Code workflows are the normal operating mode, and the platform is built around making that safe.

**Claude sessions are API consumers** — the API is designed so that Claude Code can call it directly without human-in-the-loop for reads and non-destructive writes. The coord API in particular is designed for machine callers, not humans.

**Credentials never leave the vault unencrypted** — every credential stored via the API is AES-256-GCM encrypted at the service layer before hitting the database. Audit logs are immutable and automatic.

**Softfail over hard-fail** — if the coord API is unreachable, sessions queue their calls to `.claude/coord-queue.jsonl` and continue working. The platform degrades gracefully.

**Internal-only, LAN-scoped** — the coordination API has no authentication because it is network-scoped to 172.16.3.x. External exposure would require adding auth first.

**Two users, real workflows** — features are added when a real operational gap appears, not speculatively. The Phase 7 extensions are listed but not prioritized until a specific need arises.
