jpmschweitzerandClaude
c26b54398c
One agent doc per repo, and it is CLAUDE.md. Written fresh rather than reformatted. PHILOSOPHY.md linked to the old file, so that pointer moves with it, and its standing requirement to be read before working here is carried forward rather than lost in the rewrite. Two claims did not survive verification. The app is published on 9999, not the tower:8092 the old file gave, and it pointed at portainer-core for full-stack documentation -- that repo is deprecated and must not be used as a source of infra facts. Establishing what is live needs a different method here: there is no sys.modules to read, since the container holds a compiled web build rather than source. A transitive walk of import/export/part directives from lib/main.dart found 8 of 132 files unreachable, and five of those are exactly what runs in production. They are conditional-import targets -- `import 'a.dart' if (dart.library.html) 'b.dart'` -- and a walk that takes the first string misses the branch. Since this ships as Flutter web, the _web half is live and the _stub/_native half is dormant. The naive reading was not merely wrong but inverted. Of the three genuinely unreferenced files, stack_model.dart is imported only by its own test, so the suite is green and vouches for a model the app never uses. permission_gate.dart sits next to an unimplemented auth redesign and is recorded as undetermined rather than dead. Co-Authored-By: Claude <noreply@anthropic.com>
118 lines
5.1 KiB
Markdown
118 lines
5.1 KiB
Markdown
# 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
|
|
- **CLAUDE.md**: LLM agent development guidelines
|
|
- **PLAN.md**: Implementation roadmap and phases
|
|
|
|
---
|
|
|
|
*The best interface is one you don't notice—it simply works.*
|