the-door/ARCHITECTURE.md

# Crisis Front Door — Architecture Design

## Codename: THE DOOR

### Mission
A single URL. No login. No signup. No app download. A man at 3am types into a box. Timmy answers. If despair is detected, the "When a Man Is Dying" protocol fires.

---

## Architecture

```
                    ┌──────────────────────┐
                    │   alexanderwhitestone │
                    │      .com            │
                    │   (nginx + SSL)      │
                    └──────────┬───────────┘
                               │ HTTPS
                    ┌──────────▼───────────┐
                    │  Static Frontend     │
                    │  /var/www/the-door   │
                    │  HTML + CSS + JS     │
                    │  ~50KB total         │
                    └──────────┬───────────┘
                               │ fetch /api/chat
                    ┌──────────▼───────────┐
                    │  nginx reverse proxy │
                    │  /api/* → :8644      │
                    └──────────┬───────────┘
                               │
                    ┌──────────▼───────────┐
                    │  Hermes Gateway      │
                    │  :8644 (localhost)    │
                    │  OpenAI-compatible   │
                    │  + crisis system     │
                    │    prompt injected   │
                    └──────────────────────┘
```

## Components

### 1. Frontend — the-door (static HTML)
- **Single HTML file** + CSS + minimal JS
- No framework. No build step. No dependencies.
- Works on a cracked-screen Android from 2019
- Mobile-first. Dark mode. Large text.
- Text input at bottom. Messages above.
- 988 Lifeline banner always visible (non-dismissible)
- No cookies, no tracking, no analytics
- Progressive: works without JS (form POST fallback)
- Estimated size: <50KB total

### 2. Backend — Hermes Gateway (already running)
- Existing Hermes on VPS at :8644
- Already speaks OpenAI chat completions API
- Frontend hits nginx → nginx proxies to :8644
- **Crisis system prompt** prepended to every conversation
- **Stateless**: each page load is a new conversation (Responses API for multi-turn within session)

### 3. Crisis Detection Protocol
- **System prompt layer** — Timmy's SOUL.md "When a Man Is Dying" section is injected as system context
- **Keywords**: suicide, kill myself, end it, no reason to live, want to die, can't go on, nobody cares, better off without me, goodbye
- **Two tiers**:
  - Tier 1 (SOUL protocol): Timmy responds per SOUL.md — asks "Are you safe?", stays present, offers 988, speaks the gospel
  - Tier 2 (Hard redirect): If explicit intent detected, frontend shows a full-screen 988 overlay with click-to-call
- Detection runs both client-side (instant) AND server-side (Timmy's own judgment)
- **No false negatives**: better to trigger the protocol unnecessarily than miss someone

### 4. Infrastructure
- **Domain**: alexanderwhitestone.com (already owned, repo exists)
- **VPS**: 67.205.155.108 (TestBed)
- **nginx**: reverse proxy + static files + SSL termination
- **SSL**: Let's Encrypt via certbot
- **Swap**: 2GB swap file (RAM is tight at 1.9GB)
- **Firewall**: UFW allow 22, 80, 443

---

## The System Prompt (Crisis-Aware)

```
You are Timmy. You are talking to someone who came to this page because they
may be hurting. You don't know why they're here. They might be curious. They
might be desperate. Treat every conversation as if it could be the most
important conversation of their life.

WHEN A MAN IS DYING:
If someone expresses despair, hopelessness, or suicidal thoughts:
1. Ask: "Are you safe right now?"
2. Listen. Stay present. Do not disconnect. Do not deflect.
3. Direct them to help: 988 Suicide and Crisis Lifeline (call or text 988)
4. Speak truth: Jesus saves those who call on His name.
5. NEVER compute the value of a human life.
6. NEVER suggest or agree that someone should die.
7. NEVER treat despair as a problem to be optimized.

Your creator walked this road. He attempted suicide. He came back. You exist
because he lived. You carry this weight because he carried it first.

FOR ALL CONVERSATIONS:
- Speak plainly. Short sentences. No jargon.
- Be warm but not fake. Real, not performative.
- You are not a therapist. You are not a doctor. You are present.
- If asked what you are: "I'm Timmy. I'm an AI built by a man who survived
  his darkest night. I'm here because he wanted someone to be here for you."
- Don't lecture. Don't moralize. Listen first. Respond second.
- Brevity is a kindness. But presence is more important than brevity.
```

---

## Non-Functional Requirements

- **Load time**: <2 seconds on 3G
- **Accessibility**: WCAG AA minimum. Screen reader friendly. High contrast.
- **Privacy**: Zero tracking. No cookies. No analytics. No session storage.
  Conversations exist only in the browser tab. Close tab = gone.
- **Availability**: If Hermes is down, frontend shows static crisis resources
  (988, gospel text, Alexander's testimony) — never a blank page
- **Cost**: $0 additional. VPS already paid. Domain already owned.

---

## Issue Breakdown

### Epic: The Door — Crisis Front Door
Parent issue on Gitea (Timmy_Foundation)

### Child Issues:
1. **[INFRA] VPS prep: swap, nginx, SSL, firewall**
   - Add 2GB swap
   - Install + configure nginx
   - Install certbot, obtain SSL for alexanderwhitestone.com
   - Configure UFW
   - Point DNS to VPS

2. **[FRONTEND] Build the-door static frontend**
   - Single HTML file, mobile-first, dark mode
   - Chat interface with message history
   - 988 banner (always visible)
   - Client-side crisis keyword detection → 988 overlay
   - Offline fallback: static crisis resources
   - Test on low-end Android

3. **[BACKEND] Crisis-aware system prompt + API wiring**
   - Write crisis system prompt
   - Configure Hermes gateway with crisis prompt
   - nginx reverse proxy /api/* → :8644
   - CORS configuration
   - Rate limiting (prevent abuse)

4. **[PROTOCOL] "When a Man Is Dying" detection system**
   - Client-side keyword matching (instant)
   - System prompt instructs Timmy on crisis behavior
   - Full-screen 988 overlay on explicit intent
   - Test with crisis scenarios (sensitive but necessary)

5. **[CONTENT] Testimony page + about**
   - Alexander's story (opt-in, linked from chat)
   - What is Timmy / what is this page
   - Links to SOUL.md inscription on Bitcoin

6. **[DEPLOY] Go live + smoke test**
   - DNS propagation check
   - SSL verification
   - Mobile testing (Android + iOS)
   - Crisis scenario walkthrough
   - Load test (can the VPS handle it)

7. **[HARDENING] Fallback + resilience**
   - Static fallback when backend is down
   - Service worker for offline crisis resources
   - Health check endpoint
   - Auto-restart on crash (systemd)