> ## Documentation Index
> Fetch the complete documentation index at: https://mako-docs.devinagiffy.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Core Concepts
> Understanding the key concepts in Hitler
## Bot-First Architecture
Hitler is designed with the **bot as the primary interface**. Unlike traditional SaaS apps where users interact through a web dashboard, Hitler employees interact primarily through Slack.
The web app provides an ops-brain dashboard for admins and managers, plus a simplified employee dashboard with task filters, list/board views, and pipeline access.
```
Employee ←→ Slack Bot ←→ Hitler API ←→ Database
↓
LLM Provider
```
## AI-Driven Task Creation
Hitler uses AI to parse natural language into structured tasks, which are **auto-confirmed immediately** — no draft confirmation step required. Users can modify tasks after creation via text.
### Task Flow
When an employee asks the bot to create a task:
Employee: "Remind me to review the budget proposal by Friday"
LLM extracts: title, due date, priority, description
Task is created and confirmed automatically
Bot replies with a summary of the created task(s)
User can update or cancel tasks through natural language
Each task gets a **display ID** (e.g., `#12`) for easy reference in conversation — users can say "mark #12 done" instead of typing the full title.
## Conversational AI
Hitler goes beyond simple command parsing - it's a full conversational assistant that understands context, detects intents, and maintains conversation memory.
### Intent Detection
The AI analyzes each message to determine intent:
| Intent | Description | Example |
| ------------- | --------------------------- | ----------------------------- |
| `task_create` | User wants to create a task | "I need to finish the report" |
| `task_list` | User asks about tasks | "What's on my plate?" |
| `mood` | User wants to log mood | "Log my mood" |
| `greeting` | Casual greeting | "Hey, how's it going?" |
| `general` | General conversation | "Feeling overwhelmed today" |
### Casual Task Detection
Hitler detects tasks even in casual conversation:
```
User: "tomorrow I need to do the budget review and send invoices"
Hitler automatically extracts:
1. "budget review" (due: tomorrow)
2. "send invoices" (due: tomorrow)
```
This allows natural conversation without explicit task syntax.
### Mood Inference
The AI can silently detect mood signals:
```
User: "Ugh, feeling really burned out today"
→ Inferred mood: 2 (logged silently)
→ Response: "Sounds rough, hang in there!"
```
This provides mood data without interrupting the conversation flow.
### Memory System
Hitler maintains two types of memory:
**Short-term (Redis)** - Last 10 messages - 30-minute TTL - Enables context-aware replies
**Long-term (PostgreSQL)** - User preferences (language, style) - Conversation summaries -
Pending plans
### Language Support
Hitler supports 13 languages with automatic detection and native responses:
| Language | Code | Auto-Detected |
| ------------------------ | ------------ | ------------- |
| English | `english` | Yes |
| Hinglish (Hindi-English) | `hinglish` | Yes |
| Spanish | `spanish` | Yes |
| French | `french` | Yes |
| German | `german` | Yes |
| Portuguese | `portuguese` | Yes |
| Italian | `italian` | Yes |
| Dutch | `dutch` | Yes |
| Japanese | `japanese` | Yes |
| Korean | `korean` | Yes |
| Chinese (Simplified) | `chinese` | Yes |
| Arabic | `arabic` | Yes |
| Russian | `russian` | Yes |
The bot automatically detects the language from your message and responds in the same language:
```
User: "kal mujhe report submit karna hai"
Hitler: "acha bhai, 'submit report' add kar raha"
User: "añade una tarea: revisar el informe"
Hitler: "vale, añadiendo 'revisar el informe'"
User: "タスクを追加: レポートを確認"
Hitler: "了解、「レポートを確認」を追加するね"
```
You can also manually set your preferred language in the Chat page settings. Your preference is
remembered across sessions.
## Multi-Tenancy
Hitler is built for **multi-tenant** deployment. Each organization's data is completely isolated.
| Resource | Isolation Level |
| -------------------- | ---------------------------- |
| Users | Per organization |
| Tasks | Per organization |
| Mood data | Per organization |
| Flags | Per organization |
| Platform connections | Per organization |
| Secrets (tokens) | Per organization (encrypted) |
## Roles & Permissions
Hitler uses role-based access control with three levels:
* View/manage own tasks - Log moods - Create inquiries - View own flags
* Everything Employee can do - View team tasks - View anonymized team mood stats - Resolve team
flags - Respond to inquiries
* Everything Manager can do - Manage users & roles - Configure integrations - Organization
settings - Audit logs
## Tasks
Tasks in Hitler go through a specific lifecycle:
```mermaid theme={null}
graph LR
A[Open] -->|Start| B[In Progress]
B -->|Complete| C[Completed]
A -->|Cancel| D[Cancelled]
B -->|Cancel| D
```
Tasks are auto-confirmed on creation — there is no draft confirmation step.
### Task Properties
| Property | Description |
| ------------------- | ------------------------------------------- |
| `title` | Short description (max 200 chars) |
| `displayId` | Sequential per-org number (e.g., `#12`) |
| `description` | Detailed description (optional) |
| `priority` | 1 (highest) to 5 (lowest) |
| `status` | open, in\_progress, completed, cancelled |
| `dueDate` | Optional deadline |
| `stageId` | Pipeline stage assignment (optional) |
| `size` | Task size estimate (optional) |
| `clientId` | Associated client (optional) |
| `carryForwardCount` | Times task was carried forward from EOD |
| `rawInput` | Original natural language (for AI learning) |
### Pipeline Stages
Tasks can be organized into **pipeline stages** — customizable workflow columns (e.g., "Backlog", "In Progress", "Review", "Done"). Pipeline stages are defined per organization and provide a Kanban-style view of work.
### Task Logs
Every task change is recorded in an **event log**:
```json theme={null}
{
"action": "status_changed",
"changes": {
"status": { "from": "open", "to": "in_progress" }
},
"actorId": "user-uuid",
"timestamp": "2024-01-15T10:30:00Z"
}
```
This provides full auditability and enables analytics.
## Moods
Mood tracking helps organizations understand team wellbeing over time.
### Mood Values
| Value | Meaning |
| ----- | ------------ |
| 1 | Very unhappy |
| 2 | Unhappy |
| 3 | Neutral |
| 4 | Happy |
| 5 | Very happy |
### Privacy Model
Individual mood data is **private by default**. Managers only see aggregated, anonymized
statistics.
* Employees see their own mood history and trends
* Managers see team averages and participation rates
* No manager can see an individual employee's mood entries
### Journals
Employees can also keep private **journal entries** - free-form text reflections that are never shared with anyone.
## Flags
Flags are system-detected concerns that require attention. They're raised based on patterns in mood data, task completion, and other signals.
### Severity Levels
| Level | Description | Example Trigger |
| -------- | ----------------------- | ------------------------------------ |
| Low | Minor concern | Slight mood decline |
| Medium | Moderate concern | Multiple low moods in a week |
| High | Significant concern | Consistently low mood + missed tasks |
| Critical | Urgent attention needed | Crisis indicators detected |
### Escalation Actions
Each severity level has recommended actions:
```json theme={null}
{
"severity": "high",
"actions": [
{ "action": "Schedule 1:1", "priority": 1 },
{ "action": "Review workload", "priority": 2 },
{ "action": "Offer EAP resources", "priority": 3 }
]
}
```
### Email Notifications
When a flag is created, managers automatically receive email notifications:
* **Immediate notification** - Sent when flag is created (not waiting for escalation)
* **Includes severity** - Subject line shows severity level (LOW, MEDIUM, HIGH, CRITICAL)
* **Employee context** - Shows employee name and flag reason
* **All managers notified** - Emails sent to all managers and admins in the organization
Email notifications require the `RESEND_API_KEY` environment variable to be configured. See
[Environment Variables](/development/environment-variables#email-configuration-optional).
## Inquiries
Inquiries provide a **private communication channel** between employees and HR/managers.
Inquiries can be linked to flags for context, or created independently for any HR-related
question.
### Inquiry Flow
1. Employee creates inquiry (optionally linked to a flag)
2. HR/Manager receives notification
3. Back-and-forth messaging in private thread
4. Either party can close the inquiry when resolved
## Morning Threads
The morning thread system automates daily task tracking rituals in Slack:
1. **9 AM (configurable)** — Bot posts a thread to `#today-in-progress`: "Good morning team! Share your tasks for today."
2. **Team replies** — Each user replies to the thread with what they're working on. The bot records each reply as a `thread_submission`.
3. **11 AM (configurable)** — Bot checks who hasn't replied and sends a DM reminder to missing users.
This creates a daily accountability ritual where the team shares their plans publicly and the bot tracks participation automatically.
### Follow-Up Matching
Morning thread follow-ups (submission deadline reminders) use **LLM-based matching** with scored matching to intelligently determine which users have already submitted and which are missing — rather than relying on exact string matching.
### Org Preferences
| Preference | Default | Description |
| ------------------------ | ------- | ------------------------------------- |
| `enableMorningThread` | `false` | Enable/disable morning thread system |
| `morningThreadTime` | `09:00` | When to post the morning thread |
| `submissionDeadlineTime` | `11:00` | When to check for missing submissions |
| `progressChannelId` | — | Slack channel ID for the thread |
## End-of-Day Collection
The EOD collection system closes the daily accountability loop started by the morning thread:
1. **5 PM (configurable)** — Bot posts a nudge as a reply to the morning thread: "Time to wrap up! Update your tasks with emoji statuses."
2. **7 PM (configurable)** — Bot collects EOD replies and uses **LLM per-task matching** to determine the status of each task. Instead of simple emoji parsing, the LLM analyzes each user's reply against their task list and scores how well each status update matches each task:
* Done — task marked completed
* Carry forward — task rolls to next day, `carryForwardCount` incremented
* Dropped — task cancelled
* No update — user did not reply, flagged for follow-up
3. **Summary** — Aggregated results posted to the progress channel showing team completion rates and carry-forward counts.
### EOD Org Preferences
| Preference | Default | Description |
| ------------------- | ------- | ---------------------------------------- |
| `eodNudgeTime` | `17:00` | When to post the EOD nudge to the thread |
| `eodCollectionTime` | `19:00` | When to scan and parse task statuses |
### Daily Cycle
```
9 AM — Morning thread posted (tasks for today)
11 AM — Submission deadline check (DM missing users)
5 PM — EOD nudge (reply to morning thread)
7 PM — EOD collection (parse statuses, update tasks, post summary)
```
## Notification Deduplication & Anti-Spam
Hitler uses a **two-layer dedup system** to prevent notification flooding while ensuring urgent deadlines are never missed:
### Layer 1: Task-Level Dedup (24h)
Each task can only generate one notification per user per day. Redis key `task-notif:{userId}:{taskId}:{date}` tracks whether a task was already mentioned in a morning summary, nudge, or overdue reminder. Prevents the same task from appearing in multiple messages.
### Layer 2: User-Level Cooldown (2h)
After any notification DM is sent, subsequent non-urgent nudges are suppressed for 2 hours. This prevents the 15-min proactive scanner from spamming users who just received a morning summary or batch nudge.
### Urgent Bypass
Tasks with **priority P1/P2** or **due within 2 hours** bypass the cooldown entirely. Critical deadlines always get through regardless of recent notifications.
### Example Flow
```
9:00 AM — Morning summary sent (2 overdue tasks) → cooldown starts
9:30 AM — User adds 3 new tasks
9:45 AM — Scanner fires → cooldown active, tasks are normal priority → skipped
11:15 AM — Cooldown expired → scanner sends ONE consolidated LLM nudge for 3 tasks
3:00 PM — P1 task due in 1 hour → bypasses cooldown → immediate DM
```
### Batching
The 15-min proactive scanner groups all upcoming + stale tasks by user and queues one batch nudge per user. The batch handler generates a single natural-language message via Claude Haiku covering all tasks, instead of sending separate DMs per task.
## Smart Reminders
Users can set reminders via natural language (e.g., "remind me in 1 hour about the standup"). The bot uses **LLM-based parsing** with `chrono-node` for time extraction. Reminders are stored in the database and queued as BullMQ delayed jobs, making them restart-safe. Users can snooze reminders when they fire.
## Platform Identities
Users can be linked to multiple platform identities:
```
User (john@company.com)
├── Slack: U1234567890
├── Teams: (future)
└── WhatsApp: (future)
```
This allows:
* Single sign-on via Slack/Teams
* Bot interactions linked to correct user
* Cross-platform identity resolution
## Secrets Management
Platform tokens (Slack bot tokens, etc.) are stored securely:
* **Encrypted at rest** using AES-256-GCM
* **Stored in Cloudflare KV** (not in the database)
* **Scoped per organization**
* **Short-lived in memory** - fetched, used, discarded
Key format: `org:{orgId}:{platform}:{secretType}`
Example: `org:abc123:slack:bot_token`