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:

~/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

Versioning – Increment the version in docs/CHANGELOG.md after every completed Phase task, then commit and push.
Safety – Never delete emails. Only move from INBOX to subfolders.
OTP Security – OTPs expire after 10 minutes; use bcrypt for storage; always send via TLS.
Error Handling – If AI API or IMAP fails, log the error, keep the email in INBOX, and retry on the next cycle.
tmux sessions – Do not kill the tmux session where the agent runs.
Testing – Each modular function must have its own test file (*_test.go) that can be executed independently.
Frontend – The web interface must be usable on mobile devices (responsive design, touch‑friendly inputs).

6. Immediate Actions for the Agent (OpenCode)

Create the repository named inboxer on the available Git host.
Clone it and create the exact folder structure shown above.
Place a sample .env (with placeholder values) and a default bin/classify_prompt.txt (a basic classification prompt).
Begin Phase 1 – implement OTP authentication and the mobile‑first frontend.
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.

7.6 KiB Raw Blame History Unescape Escape