Personal agent platform — self-hosted on Raspberry Pi (arm64).
| Project | Stack | What |
|---|---|---|
cockpit-api/ |
Python · FastAPI · PostgreSQL · Redis | REST API + MCP server. Integrates Vikunja, Actual Budget, brain notes. |
cockpit-app/ |
Nx · React 19 · Vue 3.5 · Tailwind · shadcn/ui | Multi-app frontend monorepo (login, cockpit, cv, store, habits). Storybook for UI docs. |
API — Modular monolith, layered per service: router → service → repository. Async SQLAlchemy, Alembic migrations, RBAC permissions.
→ docs/backend/ARCHITECTURE.md
App — Nx enforce-module-boundaries with strict layer direction: types → data-access → ui → feature → app. Cookie-based auth, TanStack Query.
→ docs/standards/frontend/architecture.md
Deployment — Docker containers on Raspberry Pi, no docker-compose in prod. nginx:alpine for apps, CI via nx affected.
→ AGENTS.md (prod stack & ports)
| Topic | File |
|---|---|
| Production containers & ports | AGENTS.md |
| API architecture & DB patterns | docs/backend/ARCHITECTURE.md |
| API dev commands (run, migrate, test) | docs/backend/DEVELOPMENT_COMMANDS.md |
| MCP tools & resources | docs/backend/MCP_SERVER.md |
| Upstream API specs (Vikunja, Actual) | docs/backend/UPSTREAM_APIS.md |
| LLM proxy & observability | docs/LITELLM_SETUP.md |
| App architecture & lib layout | docs/standards/frontend/architecture.md |
| CI/CD pipelines | .github/ |
| GitHub Secrets reference | AGENTS.md |
Root Makefile orchestrates both projects:
make install # install deps for API + App
make run # start API (docker, detached) + all frontend apps
make test # run all testsFull API dev commands: docs/backend/DEVELOPMENT_COMMANDS.md
- Deployment: Every merge to
masterauto-deploys affected projects via path-triggered GitHub Actions. No manual deploys. - Backup: Database volumes (
~/vikunja/db, PostgreSQL) must have scheduled backups on the Pi. Verify restore periodically. - Testing: Target 80% coverage (not yet enforced — will be gated in CI once reached). Write tests for new code.
- Type safety: API types auto-generated from OpenAPI spec → shared across all apps. No manual type duplication.
- Boundaries: Nx module boundary rules enforced at lint time. No cross-layer imports.
- Permissions: All business endpoints require
require_permissiondependency. No unprotected routes.
This is a personal project built for my specific use cases. You're welcome to fork it and get inspired, but be aware:
- The setup is tightly coupled to a Raspberry Pi deployment behind Cloudflare Tunnel — replicating it is time-consuming.
- It's not a general-purpose framework or template.
- I don't accept unsolicited PRs. If you'd like to contribute an improvement, contact me first so we can agree on scope before any code is written.