first commit

diagrams/README.md

@@ -0,0 +1,12 @@
+# LLM Bot Framework - Mermaid Diagrams
+
+## Diagrams
+
+| File | Description |
+|------|-------------|
+| `system.mmd` | Architecture: services, modules, and data flow |
+| `flow.mmd` | Sequence: user command from input to response |
+
+## Render
+
+Paste into https://mermaid.live/ or use VS Code "Mermaid" extension.

diagrams/flow.mmd

@@ -0,0 +1,15 @@
+sequenceDiagram
+    participant U as User
+    participant B as Bot
+    participant L as LLM
+    participant A as API
+    participant D as DB
+
+    U->>B: DM "add task buy groceries"
+    B->>L: parse message
+    L-->>B: {type: "task", action: "add", name: "buy groceries"}
+    B->>A: POST /api/tasks
+    A->>D: INSERT
+    D-->>A: {id, name, created_at}
+    A-->>B: 201 Created
+    B-->>U: "Added task: buy groceries"

diagrams/system.mmd

@@ -0,0 +1,61 @@
+flowchart TB
+    subgraph External
+        USER([User])
+        DISCORD([Discord API])
+        LLM([OpenRouter])
+        NTFY([ntfy.sh])
+    end
+
+    subgraph Bot["bot/"]
+        CLIENT[bot.py]
+        REGISTRY[command_registry.py]
+        COMMANDS[commands/]
+    end
+    
+    subgraph API["api/"]
+        FLASK[main.py]
+        ROUTES[routes/]
+    end
+    
+    subgraph Scheduler["scheduler/"]
+        DAEMON[daemon.py]
+    end
+    
+    subgraph Core["core/"]
+        AUTH[auth.py]
+        USERS[users.py]
+        PG[postgres.py]
+        NOTIF[notifications.py]
+    end
+    
+    subgraph AI["ai/"]
+        PARSER[parser.py]
+        CONFIG[ai_config.json]
+    end
+    
+    subgraph DB["db service"]
+        POSTGRES[(PostgreSQL)]
+    end
+
+    USER <-->|"DM"| DISCORD
+    DISCORD <-->|"events"| CLIENT
+    CLIENT -->|"parse"| PARSER
+    PARSER -->|"completion"| LLM
+    LLM -->|"JSON"| PARSER
+    PARSER -->|"structured data"| CLIENT
+    CLIENT -->|"get_handler"| REGISTRY
+    REGISTRY -->|"handler"| COMMANDS
+    COMMANDS -->|"logic"| CLIENT
+    CLIENT -->|"HTTP"| FLASK
+    FLASK --> ROUTES
+    FLASK --> AUTH
+    FLASK --> USERS
+    FLASK --> PG
+    AUTH --> USERS
+    USERS --> PG
+    PG --> POSTGRES
+    DAEMON --> PG
+    DAEMON --> NOTIF
+    NOTIF -->|"webhook"| DISCORD
+    NOTIF -->|"push"| NTFY
+    PARSER --> CONFIG