# Application Architecture Principles

## Purpose

Guide Nimrod when designing or improving applications/services so projects remain atomic, decoupled, modular, and easy to move, upgrade, replace, back up, and operate.

## Core Principle

A self-hosted application should normally be treated as a deployable service, not as an ad hoc process running from the current working directory.

For Nimrod-related tooling, this is especially important because the current Pi/Nimrod instance itself may move to a Proxmox LXC/server-hosted environment.

## Default Interpretation of "Self-hosted"

When the user says a tool should be self-hosted, assume:

- It should run as a managed service on homelab infrastructure, usually Proxmox.
- It should not depend on the current laptop/desktop/container unless explicitly described as a local prototype.
- It should have a service boundary, deployment plan, backup/restore plan, update plan, and runbook.
- It should follow the homelab defaults in `docs/service-deployment-defaults.md`.

## Atomic / Decoupled / Modular Defaults

Prefer designs where:

- The application code lives in its own repo or clearly separated service directory.
- Runtime deployment is separate from source/control documentation.
- Data storage is explicit and portable.
- Configuration is externalized and documented.
- Backups target the data/state, not just the application code.
- The service can be moved to another VM/LXC with minimal coupling.
- API boundaries are explicit when agents need access.
- The UI, backend/API, storage, and deployment concerns can evolve independently where practical.

## Markdown Data Considerations

Markdown remains acceptable and preferred for human-readable memory/tickets, but the storage location matters.

When building a web UI over markdown tickets, decide explicitly:

- Where canonical markdown files live
- Whether they live in the Nimrod repo, a dedicated tickets repo, or a mounted data volume
- Whether the web service writes directly to git, through an API, or through a queue/review process
- How write conflicts are handled
- How changes are audited and backed up
- How the system behaves when Nimrod/Pi moves hosts

Avoid designs where a web app casually mutates the same dirty working tree used by interactive agents.

## Recommended Pattern for Nimrod Ticket Web UI

For a self-hosted ticket CRUD UI, prefer evaluating an architecture like:

- Dedicated service repo for the application code
- Dedicated data repo or data volume for markdown tickets
- Git-backed audit trail for ticket changes
- API boundary for agent access
- Read-only mode first, then controlled writes
- Soft delete/archive instead of hard delete
- Deployment to a Proxmox LXC by default
- LAN + Tailscale access by default
- Reverse proxy/TLS integration once available

The exact implementation still requires research/specification.

## Workflow Implication

Hybrid service requests should be split into slices:

1. Product/workflow requirements
2. Data ownership and storage model
3. Application/API design
4. Deployment architecture
5. Proxmox/DNS/TLS/backups/update/dashboard integration
6. Agent integration/adoption policy, if agents will use it
7. Migration/operation plan

Do not collapse these into a single local-code task unless the user explicitly asks for a throwaway prototype.

Use `docs/hybrid-task-routing.md` for routing hybrid work.