163 lines
7.6 KiB
Markdown
163 lines
7.6 KiB
Markdown
# Project inBOXER: Master Agent Manifest
|
||
|
||
## 1. System Architecture
|
||
|
||
- **Backend:** Go (Golang) compiled binary – **modular design** (each package does one specific task).
|
||
- **Frontend:** Embedded Go templates + CSS (mobile‑first, responsive). No heavy JavaScript frameworks.
|
||
- **Database:** SQLite (single file) with GORM.
|
||
- **Authentication:** Email address + OTP (one‑time password) sent via SMTP.
|
||
- One email address = one user.
|
||
- Session stored in a secure, http‑only cookie.
|
||
- **Core Logic:** IMAP fetching → DeepSeek LLM classification → IMAP folder move.
|
||
|
||
---
|
||
|
||
## 2. Directory Structure
|
||
|
||
The agent **must** create the following exact hierarchy inside the repository:
|
||
|
||
```text
|
||
~/inboxer/ # Repository root
|
||
├── README.md
|
||
├── .env # ALL credentials (IMAP, SMTP, DeepSeek)
|
||
├── docs/
|
||
│ ├── CHANGELOG.md # Updated with each version
|
||
│ └── LICENSE.md
|
||
├── src/
|
||
│ ├── cmd/
|
||
│ │ └── main.go # Orchestrator (startup, workers, web server)
|
||
│ ├── internal/
|
||
│ │ ├── auth/ # OTP generation, email sending, session mgmt
|
||
│ │ ├── imap/ # IMAP client, batch fetching, folder ops
|
||
│ │ ├── ai/ # DeepSeek caller, prompt loader, result parser
|
||
│ │ ├── db/ # SQLite models & user settings
|
||
│ │ └── worker/ # Orchestrated cold‑start / steady‑state loop
|
||
│ ├── web/
|
||
│ │ ├── templates/ # .html files (login, dashboard, settings)
|
||
│ │ └── static/ # CSS (mobile‑first)
|
||
│ └── pkg/ # Helpers (logging, config, OTP utils)
|
||
└── bin/
|
||
├── inboxer # Compiled binary
|
||
├── config.yaml # Global settings (poll intervals, batch sizes)
|
||
├── prompt.txt # Classification prompt (loaded at runtime)
|
||
└── db.sqlite # User data & settings
|
||
```
|
||
|
||
---
|
||
|
||
## 3. Critical Agent Instructions
|
||
|
||
### A. Credentials – `.env` file
|
||
|
||
The agent **must** read `~/inboxer/.env` on startup. It contains:
|
||
|
||
```
|
||
DEEPSEEK_API_KEY=sk-...
|
||
SMTP_HOST=smtp.example.com
|
||
SMTP_PORT=587
|
||
SMTP_USER=noreply@example.com
|
||
SMTP_PASS=...
|
||
```
|
||
|
||
- No hardcoded secrets.
|
||
- The `.env` file is **never** committed to the repository.
|
||
|
||
### B. Modularity & Testability
|
||
|
||
- Each sub‑package (`auth`, `imap`, `ai`, `db`, `worker`) must expose a small, focused interface.
|
||
- The `main` package acts only as the orchestrator:
|
||
- Reads `config.yaml` and `.env`.
|
||
- Initialises database, AI client, IMAP client, OTP sender.
|
||
- Starts the web server and the background worker goroutine.
|
||
- Unit tests can target any package in isolation (each module has its own `*_test.go`).
|
||
|
||
### C. Authentication – Email + OTP
|
||
|
||
- **Login flow:**
|
||
1. User enters email address on `/login`.
|
||
2. Backend generates a 6‑digit OTP, stores it (hashed) in the database with a 10‑minute expiry.
|
||
3. OTP is sent via SMTP (credentials from `.env`) to that email address.
|
||
4. User submits OTP on `/verify`.
|
||
5. If correct, a session cookie is created (user identified by email).
|
||
- **One email = one user** – the database stores a single user’s own IMAP/SMTP mailbox settings (encrypted).
|
||
- **Session management:** cookie with `HttpOnly`, `Secure`, and appropriate expiry.
|
||
|
||
### D. Classification Prompt Location
|
||
|
||
- The prompt text file **must** be placed in `bin/prompt.txt` (next to `bin/config.yaml`).
|
||
- The binary reads this file at startup (or caches it).
|
||
- This allows end‑users to modify the classification prompt without recompiling.
|
||
|
||
### E. Repository & Version Control
|
||
|
||
- **First step:** The agent creates a new repository named `inboxer` (on GitHub/GitLab, whichever is available).
|
||
- **After each version increment** (i.e., completing a Phase task), the agent must:
|
||
- Update `docs/CHANGELOG.md` with the new version and changes.
|
||
- Commit all changes with a descriptive message.
|
||
- Push to the remote repository.
|
||
|
||
---
|
||
|
||
## 4. Phased Project Plan
|
||
|
||
### Phase 1: Foundation, OTP Auth & Mobile Frontend (Version: 2026-04.1)
|
||
|
||
- **1.1** Create repository `inboxer` and the exact folder structure.
|
||
- **1.2** Go module init, add dependencies: `go-imap`, `gorm`, `sqlite`, `slog`, etc.
|
||
- **1.3** Implement `.env` loader + `config.yaml` parser.
|
||
- **1.4** **Modular auth package:**
|
||
- OTP generation & hashing (bcrypt)
|
||
- SMTP sender (using `.env` credentials)
|
||
- Session cookie management
|
||
- **1.5** **Mobile‑first frontend** (Go templates + CSS grid/flex):
|
||
- `/login` – email input
|
||
- `/verify` – OTP input
|
||
- `/dashboard` – shows processing status, last run, folder counts
|
||
- `/settings` – user can set their own IMAP/SMTP credentials (encrypted in DB)
|
||
- **1.6** SQLite schema: `users` (email, hashed_otp, otp_expiry), `mailbox_settings` (imap_host, imap_user, encrypted_pass, etc.).
|
||
|
||
### Phase 2: IMAP & Cold‑Start Worker (Version: 2026-04.2)
|
||
|
||
- **2.1** **Modular IMAP package** – connect, list folders, move messages, fetch batches.
|
||
- **2.2** **Worker orchestrator:**
|
||
- Steady state: 10 emails every 5 minutes.
|
||
- Catch‑up mode (if `last_processed_uid` is null): batches of 50 emails, 5‑second cooldown between batches.
|
||
- **2.3** Ensure folders `Important`, `eCommerce`, `Other`, `Spam` exist (create if missing).
|
||
|
||
### Phase 3: DeepSeek AI & Prompt Loading (Version: 2026-04.3)
|
||
|
||
- **3.1** **Modular AI package** – reads `bin/classify_prompt.txt` and caches it.
|
||
- **3.2** Sends (sender, subject, body snippet) to DeepSeek, expects JSON: `{"folder": string, "score": int, "context": string}`.
|
||
- **3.3** If AI fails (API error, invalid response), the email stays in `INBOX` (no guessing).
|
||
- **3.4** Add “Test Mode” toggle in frontend – logs AI decisions without moving physical emails.
|
||
|
||
### Phase 4: Reporting, Logging & Final Polish (Version: 2026-04.4)
|
||
|
||
- **4.1** Weekly summary report – sent via SMTP (from `.env`) to the logged‑in user’s email.
|
||
- **4.2** Structured logging (`slog`) to `bin/inboxer.log`.
|
||
- **4.3** `Makefile` with targets: `build`, `run`, `test`.
|
||
- **4.4** Final binary placed in `bin/` – ready for end‑user distribution.
|
||
|
||
---
|
||
|
||
## 5. Operational Guardrails for the AI Agent
|
||
|
||
1. **Versioning** – Increment the version in `docs/CHANGELOG.md` after every completed Phase task, then **commit and push**.
|
||
2. **Safety** – Never delete emails. Only move from `INBOX` to subfolders.
|
||
3. **OTP Security** – OTPs expire after 10 minutes; use bcrypt for storage; always send via TLS.
|
||
4. **Error Handling** – If AI API or IMAP fails, log the error, keep the email in `INBOX`, and retry on the next cycle.
|
||
5. **tmux sessions** – Do not kill the tmux session where the agent runs.
|
||
6. **Testing** – Each modular function must have its own test file (`*_test.go`) that can be executed independently.
|
||
7. **Frontend** – The web interface must be usable on mobile devices (responsive design, touch‑friendly inputs).
|
||
|
||
---
|
||
|
||
## 6. Immediate Actions for the Agent (OpenCode)
|
||
|
||
1. **Create the repository** named `inboxer` on the available Git host.
|
||
2. **Clone it** and create the exact folder structure shown above.
|
||
3. **Place a sample `.env`** (with placeholder values) and a default `bin/classify_prompt.txt` (a basic classification prompt).
|
||
4. **Begin Phase 1** – implement OTP authentication and the mobile‑first frontend.
|
||
5. **After finishing Phase 1**, update `CHANGELOG.md` to version `2026-04.1`, then **commit and push**.
|
||
|
||
The agent is now cleared to execute. All subsequent commits must follow the same pattern after each version increment.
|