arsam
5e501bfcae
Import the existing local project snapshot. This commit organizes existing files; it does not represent newly developed functionality.
63 lines
3.5 KiB
Markdown
63 lines
3.5 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure
|
|
|
|
NOVA is a TypeScript Telegram AI bot. Two source files hold everything:
|
|
|
|
- `index.ts` — entry point, calls `startNova()` from `src/bot.ts`
|
|
- `src/bot.ts` — ~7000 lines, single file containing all bot logic (Telegram polling, Gemini tool calling, session management, admin commands, image gen, voice, reminders, PDF, web apps, scheduler)
|
|
- `src/kv.ts` — `SqliteKV` class implementing a Cloudflare-KV-style interface over `better-sqlite3` (`kv_store` table with optional TTL)
|
|
- `nova.db` — runtime SQLite database (gitignored; `/data/nova.db` inside Docker)
|
|
|
|
There is no build step. `tsx` runs TypeScript directly.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
npm install # install deps
|
|
npm run dev # tsx watch index.ts — auto-restart on change
|
|
npm start # tsx index.ts — production long-polling
|
|
npm run type-check # tsc --noEmit — required validation before submitting
|
|
docker compose up -d # container with restart policy, healthcheck, persistent nova-data volume
|
|
```
|
|
|
|
There is no test framework. `npm run type-check` is the only automated check.
|
|
|
|
## Architecture Notes
|
|
|
|
- **Update mode**: Telegram Bot API long polling via `getUpdates`. No webhooks.
|
|
- **Express server** on `PORT` (default 3000): serves `/health` endpoint and hosted web apps at `/app/:name`.
|
|
- **Scheduler**: `setInterval` calls `runScheduled()` every 5 minutes for reminders, broadcasts, and cleanup.
|
|
- **Session model**: `ChatSession` stored in KV under `session:<chatId>`. In-memory `CacheLayer<ChatSession>` (200 entries, 3 min TTL) wraps hot reads.
|
|
- **Tool calling**: Gemini function-calling drives bot features (image gen, web search, voice, PDF, reminders, admin actions). Tool results fed back as `functionResponse` parts.
|
|
- **Key rotation**: Gemini keys (`GEMINI_KEY_1..5`), ElevenLabs keys (`ELEVENLABS_KEY_1..5`), Cloudflare pairs (`CF_ID_1..3`/`CF_TOKEN_1..3`). Disabled keys tracked in KV, auto-rotated on failure.
|
|
- **Rate limiting**: `TokenBucket` per user, daily limits per session type, in-memory dedup via `activeProgressMessages`.
|
|
- **Bot config**: persisted in KV under `bot_config` key with runtime defaults. Editable via owner Telegram commands.
|
|
- **Bot version**: `BOT_VERSION` constant at top of `src/bot.ts`.
|
|
|
|
## Coding Conventions
|
|
|
|
- TypeScript `strict` mode. Two-space indent, semicolons, single quotes.
|
|
- `camelCase` for functions/variables, `PascalCase` for interfaces/classes.
|
|
- Sections in `bot.ts` are separated by `// SECTION:` comment banners — keep new logic in labeled sections.
|
|
- Prefer typed interfaces; avoid `any` unless local and unavoidable.
|
|
- State goes through `SqliteKV` (async API matching Cloudflare KV). Never read/write `nova.db` directly.
|
|
|
|
## Configuration
|
|
|
|
Loaded from `.env` via `dotenv/config` (imported as first line in `bot.ts`). Required:
|
|
|
|
- `TOKEN` — Telegram bot token (app exits if missing)
|
|
- `BOT_OWNER_ID` — primary owner user ID (number)
|
|
- `ADDITIONAL_OWNER_IDS` — comma-separated extra owner IDs
|
|
|
|
Optional provider keys: `GEMINI_KEY_*`, `ELEVENLABS_KEY_*`, `CF_ID_*`/`CF_TOKEN_*`, `GOOGLE_SEARCH_API_KEY`, `GOOGLE_SEARCH_ENGINE_ID`.
|
|
|
|
`DB_PATH` defaults to `./nova.db`, overridden to `/data/nova.db` in Docker.
|
|
|
|
## Security Constraints
|
|
|
|
- `/eval` is permanently disabled. Never reintroduce shell access, `child_process`, runtime JS eval, or AI-triggered command execution.
|
|
- Owner access is strictly via `BOT_OWNER_ID` + `ADDITIONAL_OWNER_IDS` env vars. No username-based or hidden escalation.
|
|
- `.env`, API keys, bot tokens, and Cloudflare tokens are sensitive. Never log or commit them.
|