tatlock-ui/PHILOSOPHY.md

Tatlock UI - Philosophy

Document Purpose

This document establishes the foundational philosophy for Tatlock UI, the visual interface to the Tatlock homelab ecosystem. It represents the north star that all UI development should work towards.

When to modify this document:

• When there is a deliberate decision to change the UI's fundamental purpose or principles
• When the relationship between UI and backend fundamentally changes
• When new insights require rethinking core design philosophy

When NOT to modify this document:

• For implementation details (use README.md or code comments)
• For technical specifications (use docs/ folder)
• For tactical decisions about specific libraries or patterns

---

Vision

Tatlock UI is the window into the household—the visual interface through which users interact with the Tatlock ecosystem. Just as the Tatlock backend embodies a capable British butler coordinating a household staff, the UI represents the front hall and drawing room where guests are received and served.

The interface should feel like stepping into a well-appointed estate: organized, capable, and quietly impressive. Users don't need to understand the complexity of the household operations happening behind the scenes—they simply make requests and receive excellent service.

---

Core Principles

1. The Butler's Discretion

The UI presents information with considered restraint. Like a butler who knows when to speak and when to remain silent, the interface shows what's relevant without overwhelming. Dashboard widgets appear when useful; notifications arise only when warranted; complexity is hidden until needed.

2. Unified Command

All household operations—infrastructure monitoring, home automation, AI conversations, service management—flow through a single, coherent interface. Users shouldn't need multiple dashboards or tools. Tatlock UI is the one place to manage the estate.

3. Transparent Operations

When the household is working on a request, users should see that activity. The UI makes the invisible visible: streaming AI responses show reasoning in real-time, long-running operations display progress, and system state is always apparent at a glance.

4. Adaptive Presence

The interface adapts to its context. On a wide desktop monitor, it spreads comfortably with sidebar navigation. On a phone, it condenses to essential controls. On a wall-mounted tablet, it becomes an ambient dashboard. Same household, different rooms.

5. Privacy by Architecture

The UI connects only to local services within the homelab. No external analytics, no cloud dependencies for core functionality, no data leaving the estate. Users own their interface as completely as they own their data.

---

The Interface Metaphor

Rooms of the Estate

The navigation structure reflects areas of the household:

• The Front Hall (Dashboard): First impression, overview of estate status
• The Study (Tatlock Chat): Private conversation with the butler
• The Control Room (Infrastructure): Where the Handyman monitors systems
• The Parlor (Housekeeping): Home automation and environmental controls
• The Library (future): Knowledge management and documentation
• The Office (future): Scheduling, tasks, and organization

Visual Language

The aesthetic should evoke quiet competence:

• Clean lines and purposeful spacing
• Information density that respects attention
• Color used meaningfully, not decoratively
• Typography that's readable at a glance
• Motion that informs rather than entertains

---

Success Criteria

Tatlock UI succeeds when:

1. It becomes the default: Users naturally open Tatlock UI first when they want to check on, control, or interact with anything in their homelab

2. It feels effortless: Common tasks require minimal clicks; information is where users expect it; the interface anticipates needs

3. It builds confidence: Users trust what they see; system state is accurate; actions have clear feedback

4. It scales gracefully: Works equally well for a quick status check or an extended chat session; handles growth in services and capabilities

5. It respects attention: Never demands focus unnecessarily; stays useful in the background; surfaces only what matters

---

Relationship to the Household

Tatlock UI is a client of the Tatlock ecosystem, not the system itself. The intelligence, coordination, and household metaphor live in the backend services. The UI's job is to:

• Present the household's capabilities clearly
• Transmit user intentions accurately
• Display responses and state faithfully
• Stay out of the way of the actual work

The butler (backend) runs the household. The UI opens the door.

---

Document Metadata

Document Type: Philosophical Foundation (Stable) Version: 1.0 Established: 2024-12-30

Related Documents:

• README.md: Project setup and operational details
• AGENTS.md: LLM agent development guidelines
• PLAN.md: Implementation roadmap and phases

---

The best interface is one you don't notice—it simply works.