# moonlin1213/cove-pet-nest architecture

> Architecture diagram of the GitHub repository moonlin1213/cove-pet-nest, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/moonlin1213/cove-pet-nest
- Repository: https://github.com/moonlin1213/cove-pet-nest

## Overview

Cove Pet Nest is a local pet-care application that integrates with a user’s AI through stdio MCP or authenticated HTTP. The principal workflow is to adopt a pet, build pantry food from host-reported conversation contributions, and record care; for fantasy eggs, growth and relationship signals shape a frozen hatch description that can be sent to an optional image service. The local web UI and MCP expose care, while HTTP also handles host events and image imports. SQLite-backed state supports receipts and retries. Some UI and backup internals were not sampled; documented capabilities are included without assuming their implementation details.

Main entry points: [`src/cove_pet_nest/http.py`](https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/http.py) (HTTP API), [`src/cove_pet_nest/service.py`](https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/service.py) (Nest service), [`src/cove_pet_nest/store.py`](https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/store.py) (SQLite pet store), [`src/cove_pet_nest/images/service.py`](https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/images/service.py) (Image jobs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_web["Local web UI"]
  node_http["HTTP API<br/>[http.py]"]
  node_mcp["MCP tools<br/>[mcp_server.py]"]
  node_entry["Service entry<br/>[cli.py]"]
  node_contracts["Request contracts<br/>[contracts.py]"]
end

subgraph group_domain["Pet domain"]
  node_service["Nest service<br/>[service.py]"]
  node_care["Adoption and care<br/>[store.py]"]
  node_growth["Hatch preparation<br/>[growth.py]"]
end

subgraph group_signals["Contribution signals"]
  node_usage["Usage ledger<br/>[ledger.py]"]
  node_relationship["Relationship signals<br/>[relationships.py]"]
end

subgraph group_images["Images and hatching"]
  node_jobs["Image jobs<br/>[service.py]"]
  node_processing["Image validation<br/>[processing.py]"]
  node_transport["Image provider transport<br/>[transport.py]"]
end

subgraph group_localdata["Local data"]
  node_store[("SQLite pet store<br/>[store.py]")]
  node_auth["Local credentials<br/>[auth.py]"]
  node_backup["Backup and restore<br/>[backup.py]"]
end

node_user(("Pet owner"))
node_host(("Host application"))
node_imageprovider["Image generation service"]

node_user -->|"uses"| node_web
node_web -.->|"requests"| node_http
node_host -->|"reports events"| node_http
node_entry -->|"builds"| node_service
node_entry -->|"serves"| node_http
node_entry -->|"runs"| node_mcp
node_http -->|"checks credentials"| node_auth
node_http -->|"validates requests"| node_contracts
node_http -->|"routes pet actions"| node_service
node_http -->|"records usage"| node_usage
node_http -->|"records signals"| node_relationship
node_http -->|"imports assets"| node_jobs
node_http -->|"ticks worker"| node_service
node_mcp -->|"validates tool input"| node_contracts
node_mcp -->|"calls pet actions"| node_service
node_service -->|"adopts and cares"| node_care
node_service -->|"queues and runs"| node_jobs
node_service -->|"prepares hatch"| node_growth
node_service -->|"reads state"| node_store
node_jobs -->|"validates images"| node_processing
node_jobs -->|"requests generation"| node_transport
node_transport -.->|"sends prompt"| node_imageprovider
node_jobs -->|"records job state"| node_store
node_growth -->|"reads signals and care"| node_store
node_usage -->|"credits pantry"| node_store
node_relationship -->|"stores signals"| node_store
node_entry -->|"creates backup"| node_backup
node_backup -->|"backs up database"| node_store

click node_web "https://github.com/moonlin1213/cove-pet-nest/tree/main/src/cove_pet_nest/web"
click node_http "https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/http.py"
click node_mcp "https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/mcp_server.py"
click node_entry "https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/cli.py"
click node_service "https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/service.py"
click node_care "https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/store.py"
click node_growth "https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/growth.py"
click node_usage "https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/ledger.py"
click node_relationship "https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/relationships.py"
click node_contracts "https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/contracts.py"
click node_jobs "https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/images/service.py"
click node_processing "https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/images/processing.py"
click node_transport "https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/images/transport.py"
click node_store "https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/store.py"
click node_auth "https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/auth.py"
click node_backup "https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/backup.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web,node_http,node_mcp,node_entry,node_contracts toneBlue
class node_service,node_care,node_growth toneAmber
class node_usage,node_relationship toneMint
class node_jobs,node_processing,node_transport toneRose
class node_store,node_auth,node_backup,node_user,node_host,node_imageprovider toneIndigo
```

## Components

### User interfaces

- [Local web UI](https://github.com/moonlin1213/cove-pet-nest/tree/main/src/cove_pet_nest/web): `src/cove_pet_nest/web`
- [HTTP API](https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/http.py): `src/cove_pet_nest/http.py`
- [MCP tools](https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/mcp_server.py): `src/cove_pet_nest/mcp_server.py`
- [Service entry](https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/cli.py): `src/cove_pet_nest/cli.py`
- [Request contracts](https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/contracts.py): `src/cove_pet_nest/contracts.py`

### Pet domain

- [Nest service](https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/service.py): `src/cove_pet_nest/service.py`
- [Adoption and care](https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/store.py): `src/cove_pet_nest/store.py`
- [Hatch preparation](https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/growth.py): `src/cove_pet_nest/growth.py`

### Contribution signals

- [Usage ledger](https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/ledger.py): `src/cove_pet_nest/ledger.py`
- [Relationship signals](https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/relationships.py): `src/cove_pet_nest/relationships.py`

### Images and hatching

- [Image jobs](https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/images/service.py): `src/cove_pet_nest/images/service.py`
- [Image validation](https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/images/processing.py): `src/cove_pet_nest/images/processing.py`
- [Image provider transport](https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/images/transport.py): `src/cove_pet_nest/images/transport.py`

### Local data

- [SQLite pet store](https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/store.py): `src/cove_pet_nest/store.py`
- [Local credentials](https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/auth.py): `src/cove_pet_nest/auth.py`
- [Backup and restore](https://github.com/moonlin1213/cove-pet-nest/blob/main/src/cove_pet_nest/backup.py): `src/cove_pet_nest/backup.py`

### Other components

- **Pet owner**
- **Host application**
- **Image generation service**

## Connections

- Pet owner → Local web UI: uses (evidence: `README.md`)
- Local web UI → HTTP API: requests
- Host application → HTTP API: reports events (evidence: `README.md`)
- Service entry → Nest service: builds (evidence: `src/cove_pet_nest/cli.py`)
- Service entry → HTTP API: serves (evidence: `src/cove_pet_nest/cli.py`)
- Service entry → MCP tools: runs (evidence: `src/cove_pet_nest/cli.py`)
- HTTP API → Local credentials: checks credentials (evidence: `src/cove_pet_nest/http.py`)
- HTTP API → Request contracts: validates requests (evidence: `src/cove_pet_nest/http.py`)
- HTTP API → Nest service: routes pet actions (evidence: `src/cove_pet_nest/http.py`)
- HTTP API → Usage ledger: records usage (evidence: `src/cove_pet_nest/http.py`)
- HTTP API → Relationship signals: records signals (evidence: `src/cove_pet_nest/http.py`)
- HTTP API → Image jobs: imports assets (evidence: `src/cove_pet_nest/http.py`)
- HTTP API → Nest service: ticks worker (evidence: `src/cove_pet_nest/http.py`)
- MCP tools → Request contracts: validates tool input (evidence: `src/cove_pet_nest/mcp_server.py`)
- MCP tools → Nest service: calls pet actions (evidence: `src/cove_pet_nest/mcp_server.py`)
- Nest service → Adoption and care: adopts and cares (evidence: `src/cove_pet_nest/service.py`)
- Nest service → Image jobs: queues and runs (evidence: `src/cove_pet_nest/service.py`)
- Nest service → Hatch preparation: prepares hatch (evidence: `src/cove_pet_nest/service.py`)
- Nest service → SQLite pet store: reads state (evidence: `src/cove_pet_nest/service.py`)
- Image jobs → Image validation: validates images (evidence: `src/cove_pet_nest/images/service.py`)
- Image jobs → Image provider transport: requests generation (evidence: `src/cove_pet_nest/images/service.py`)
- Image provider transport → Image generation service: sends prompt (evidence: `src/cove_pet_nest/images/transport.py`)
- Image jobs → SQLite pet store: records job state (evidence: `src/cove_pet_nest/images/service.py`)
- Hatch preparation → SQLite pet store: reads signals and care (evidence: `src/cove_pet_nest/growth.py`)
- Usage ledger → SQLite pet store: credits pantry (evidence: `src/cove_pet_nest/ledger.py`)
- Relationship signals → SQLite pet store: stores signals (evidence: `src/cove_pet_nest/relationships.py`)
- Service entry → Backup and restore: creates backup (evidence: `src/cove_pet_nest/cli.py`)
- Backup and restore → SQLite pet store: backs up database (evidence: `src/cove_pet_nest/backup.py`)
