arsam
143be86cc3
Import the existing local project snapshot. This commit organizes existing files; it does not represent newly developed functionality.
52 lines
2.2 KiB
Markdown
52 lines
2.2 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code when working with this repository.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
npm run dev # Run root index.ts in watch mode
|
|
npm start # Start the bot process
|
|
npm run type-check # TypeScript type-check without emit
|
|
docker compose up -d # Run with restart policy and persistent nova-data volume
|
|
```
|
|
|
|
There is no test suite. Type checking is the required validation step.
|
|
|
|
## Architecture
|
|
|
|
NOVA is a Telegram AI chatbot running as a Node.js process, suitable for Docker/container deployment.
|
|
|
|
- **Entry point**: `index.ts`
|
|
- **Core bot**: `src/bot.ts`
|
|
- **Local KV adapter**: `src/kv.ts`
|
|
- **Storage**: `nova.db` through a SQLite-backed KV interface
|
|
- **Configuration**: `.env`
|
|
- **Telegram update mode**: Bot API long polling via `getUpdates`; no webhook route is registered
|
|
- **Scheduled work**: in-process `setInterval` calls `runScheduled()` every five minutes for reminders, recurring tasks, broadcasts, and cleanup
|
|
|
|
## External APIs
|
|
|
|
| Service | Purpose | Key rotation |
|
|
|---|---|---|
|
|
| Google Gemini | LLM, function calling, voice transcription | `GEMINI_KEY_1..5` |
|
|
| ElevenLabs | Text-to-speech voice responses | `ELEVENLABS_KEY_1..5` |
|
|
| Cloudflare Workers AI REST API | Image generation | `CF_ID_1..3` / `CF_TOKEN_1..3` |
|
|
| Google Custom Search | Web and image search | `GOOGLE_SEARCH_API_KEY`, `GOOGLE_SEARCH_ENGINE_ID` |
|
|
|
|
## Ownership
|
|
|
|
Administrative access is explicit. `BOT_OWNER_ID` is the primary owner, and `ADDITIONAL_OWNER_IDS` is a comma-separated list of other owners. Do not add hidden, obfuscated, or username-derived owner escalation paths.
|
|
|
|
## Runtime Safety
|
|
|
|
The Telegram `/eval` command is intentionally disabled. Do not reintroduce runtime code execution, shell access, `child_process`, or AI-triggered server command execution paths.
|
|
|
|
## State Model
|
|
|
|
`ChatSession` is stored in KV under `session:<chatId>`. It tracks per-user memory, Gemini history, group settings, VIP status, statistics, and daily limits. `CacheLayer<T>` wraps hot session reads in memory.
|
|
|
|
## Tool Calling
|
|
|
|
Gemini function calling is used for bot tools such as image generation, web search, file download, PDF creation, hosted web apps, reminders, voice response, and admin actions. Tool results are fed back into Gemini as `functionResponse` parts.
|