Skip to content

Commit 2476e6c

Browse files
chiliecchiliec
committed
Add agent context files and future ideas
1 parent ec319e5 commit 2476e6c

5 files changed

Lines changed: 375 additions & 34 deletions

File tree

‎.gitignore‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -139,4 +139,5 @@ data/
139139

140140
# Ignore SQLite database
141141
*.db
142-
*.db-journal
142+
*.db-journal
143+
.claude

‎AGENTS.md‎

Lines changed: 57 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,70 @@
1-
# Codex Project Guide
1+
# Agent Project Guide
22

33
## Project Summary
4-
Cube Worlds is a Telegram bot plus a Vue 3 web frontend for an NFT game. The backend is TypeScript (Node 18+), using grammy for the bot, Fastify/Hono for HTTP, and MongoDB via Mongoose. The frontend is a Vite + Vue 3 app under `src/frontend`.
54

6-
See `ARCHITECTURE.md` for a concise system overview.
5+
Cube Worlds is a Telegram Mini App game on the TON blockchain. Three main parts: a Telegram bot (Grammy), a Fastify API backend, and a Vue 3 frontend (Vite). Data stored in MongoDB via Typegoose.
6+
7+
See `CLAUDE.md` for comprehensive project context. See `ARCHITECTURE.md` for system overview.
78

89
## Repository Layout
9-
- `src/main.ts`: bot entrypoint (ts-node/tsx dev).
10-
- `src/bot/`: bot logic (handlers, commands, menus).
11-
- `src/backend/`: backend services and data access.
12-
- `src/server.ts`: HTTP server integration.
13-
- `src/frontend/`: Vue 3 web app (own `package.json`).
14-
- `data/`, `locales/`: content assets and i18n resources.
10+
11+
- `src/main.ts` — Bot entrypoint: MongoDB connect → bot init → server start → subscription start
12+
- `src/bot/` — Bot logic: features (commands), middlewares, helpers
13+
- `src/backend/handlers/` — Fastify route handlers (auth, claim, nft, leaderboard, balances)
14+
- `src/server.ts` — HTTP server: webhooks, static files, API routes under `/api/`
15+
- `src/common/models/` — Typegoose models: User, Balance, Claim, CNFT, Transaction, Vote
16+
- `src/common/helpers/` — Shared utils: TON blockchain, IPFS, image generation, telegram
17+
- `src/config.ts` — Environment config via znv (lazy singleton proxy)
18+
- `src/subscription.ts` — TON transaction monitoring service
19+
- `src/frontend/` — Vue 3 web app (separate `package.json`)
20+
- `locales/` — i18n translation files (Fluent .ftl)
21+
- `data/` — Static assets (NFT images, fonts)
1522

1623
## Environment
17-
- Node >= 18, npm >= 8.
18-
- `.env` is required. Copy from `.env.example` and fill in tokens/keys.
19-
- MongoDB connection string is required (`MONGO`).
24+
25+
- Node >= 18, npm >= 8
26+
- `.env` required — copy from `.env.example`
27+
- MongoDB connection string required (`MONGO`)
28+
- Key external services: Telegram Bot API, TON blockchain, Pinata (IPFS)
29+
- Optional: OpenAI, Stability AI, Telemetree
2030

2131
## Common Commands
22-
- `npm install` (root) installs backend deps.
23-
- `npm --prefix src/frontend install` installs frontend deps.
24-
- `npm run dev` runs backend in watch mode.
25-
- `npm --prefix src/frontend run dev` runs frontend in Vite dev server.
26-
- `npm run build:all` builds backend and frontend.
27-
- `npm run lint` runs ESLint.
28-
- `npm run format` runs Prettier.
29-
- `npm run typecheck` runs TypeScript.
32+
33+
```bash
34+
npm install && npm --prefix src/frontend install # Install all deps
35+
npm run dev # Backend watch mode
36+
npm --prefix src/frontend run dev # Frontend dev server (port 5173)
37+
npm run build:all # Build backend + frontend
38+
npm run lint # ESLint
39+
npm run format # Prettier
40+
npm run typecheck # TypeScript check
41+
npm run test:backend # Run backend tests (Node.js test runner)
42+
```
3043

3144
## Notes for Agents
32-
- This repo is ESM (`"type": "module"`). Keep imports ESM-compatible.
33-
- Prefer editing TypeScript sources under `src/` and avoid touching `build/` unless explicitly asked.
34-
- Keep `src/frontend` changes isolated to that subtree (it is its own package).
35-
- When changing runtime behavior, check both bot entry (`src/main.ts`) and server integration (`src/server.ts`).
45+
46+
- This repo is **ESM** (`"type": "module"`). All imports must be ESM-compatible.
47+
- Path aliases: `#root/*` → `./build/src/*` (backend), `@/*` → `./src/*` (frontend).
48+
- Prefer editing TypeScript sources under `src/`. Never touch `build/`.
49+
- Frontend (`src/frontend/`) is its own package — keep changes isolated there.
50+
- When changing runtime behavior, check both `src/main.ts` and `src/server.ts`.
51+
- Typegoose uses decorators — `experimentalDecorators` and `emitDecoratorMetadata` are required.
52+
- Code style: no semicolons, single quotes, 2-space indent (Prettier enforced).
3653

3754
## Testing
38-
- No dedicated test runner is configured. Use `npm run lint` and `npm run typecheck` as safety checks.
55+
56+
- **Runner:** Node.js built-in test module (`node --test`)
57+
- **Command:** `npm run test:backend`
58+
- **Tested handlers:** auth, claim, set-wallet, balances, leaderboard
59+
- **Untested:** nft-handler
60+
- Always run `npm run lint && npm run typecheck` as safety checks after changes.
61+
62+
## Known TODOs
63+
64+
- `src/bot/features/play.ts:41` — Save conversation to DB for story game persistence
65+
- `src/common/helpers/telegram.ts:114` — Complete user activity tracking logic
66+
- `src/bot/features/admin/queue.ts:244` — Re-enable sendNewPlaces notification
67+
68+
## Future Development
69+
70+
See `docs/FUTURE_DEVELOPMENT.md` for a prioritized list of improvements and new feature ideas.

‎CLAUDE.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# Claude Code Project Guide
2+
3+
## Project Summary
4+
5+
Cube Worlds is a Telegram Mini App game built around NFTs on the TON blockchain. It consists of three main parts: a Telegram bot (Grammy), a backend API (Fastify), and a Vue 3 frontend (Vite). Data is stored in MongoDB via Typegoose.
6+
7+
## Repository Layout
8+
9+
```
10+
src/
11+
main.ts # Bot entrypoint: MongoDB connect, bot init, server start
12+
server.ts # Fastify HTTP server: webhooks, static files, API routes
13+
config.ts # Environment config via znv (lazy singleton proxy)
14+
logger.ts # Pino logger (silent in test mode)
15+
subscription.ts # TON transaction monitoring service
16+
bot/
17+
index.ts # Bot creation, middleware chain, feature registration
18+
features/ # Bot command handlers (start, mint, dice, play, admin/*)
19+
helpers/ # Bot-specific utilities (keyboards, session, context)
20+
middlewares/ # Grammy middlewares (i18n, user attach, session)
21+
backend/
22+
handlers/ # Fastify route handlers (auth, claim, nft, leaderboard, balances)
23+
*.test.ts # Backend tests (Node.js built-in test runner)
24+
common/
25+
models/ # Typegoose models: User, Balance, Claim, CNFT, Transaction, Vote
26+
helpers/ # Shared utilities: ton.ts, ipfs.ts, generation.ts, telegram.ts
27+
frontend/ # Separate npm package (Vue 3 + Vite)
28+
src/
29+
views/ # Vue components (Claim, Leaderboard, Exchange, Mining, Clicker, CNFT, FAQ)
30+
router/ # Vue Router config
31+
stores/ # Pinia stores (userStore)
32+
services/ # API service wrappers (auth, wallet)
33+
locales/ # i18n translation files (Fluent .ftl format)
34+
data/ # Static assets (NFT images, fonts)
35+
```
36+
37+
## Tech Stack
38+
39+
- **Runtime:** Node.js 18+, TypeScript, ESM modules
40+
- **Bot:** Grammy 1.40 (Telegram Bot API)
41+
- **HTTP:** Fastify 5.7
42+
- **Database:** MongoDB via Mongoose 8 + Typegoose 12
43+
- **Frontend:** Vue 3.5, Vite 7, Pinia, Element Plus, Vue Router
44+
- **Blockchain:** TON (@ton/core, @ton/ton, TonConnect SDK, TonWeb)
45+
- **External APIs:** Pinata (IPFS), OpenAI, Stability AI, Telemetree
46+
- **Testing:** Node.js built-in test runner (`node --test`)
47+
48+
## Key Commands
49+
50+
```bash
51+
npm install && npm --prefix src/frontend install # Install all deps
52+
npm run dev # Backend watch mode (tsx)
53+
npm --prefix src/frontend run dev # Frontend dev server (port 5173)
54+
npm run build:all # Build backend (tsc) + frontend (vite)
55+
npm run lint # ESLint
56+
npm run format # Prettier
57+
npm run typecheck # TypeScript check
58+
npm run test:backend # Run backend tests
59+
```
60+
61+
## Conventions
62+
63+
- **ESM only** — no CommonJS `require()`. Use `import` everywhere.
64+
- **Path alias:** `#root/*` maps to `./build/src/*` (backend). `@/*` maps to `./src/*` (frontend).
65+
- **Separate packages:** Frontend has its own `package.json` under `src/frontend/`.
66+
- **Don't touch `build/`** — it's generated output from `tsc`.
67+
- **Typegoose decorators** require `experimentalDecorators` and `emitDecoratorMetadata`.
68+
- **No semicolons**, single quotes, 2-space indent (Prettier config).
69+
70+
## Data Models
71+
72+
| Model | Purpose | Key Fields |
73+
|-------|---------|------------|
74+
| User | Telegram user profile + game state | id, wallet, votes, state, minted, referalId |
75+
| Balance | Balance change history | userId, amount (bigint), type (enum), createdAt |
76+
| Claim | Daily claim rewards with streaks | user (ref), streakDays, lastClaimDate, totalClaimed |
77+
| CNFT | Compressed NFT metadata | index, userId, wallet, votes, type, color, minted |
78+
| Transaction | TON transaction records | utime, lt, address, coins, hash, accepted |
79+
| Vote | Referral tracking | giver, receiver, quantity |
80+
81+
## API Endpoints (all under `/api/`)
82+
83+
| Method | Path | Purpose |
84+
|--------|------|---------|
85+
| POST | /api/auth/login | Authenticate via Telegram initData |
86+
| POST | /api/auth/set-wallet | Store user's TON wallet |
87+
| POST | /api/captcha | Bot captcha verification |
88+
| GET | /api/nft/:index | NFT metadata + image serving |
89+
| GET | /api/users/balance | User balance query |
90+
| GET | /api/users/leaderboard | Ranked leaderboard |
91+
| POST | /api/users/claim | Daily reward claim |
92+
93+
## Bot Features
94+
95+
Core commands: `/start`, `/mint`, `/dice`, `/balance`, `/whales`, `/webapp`
96+
Admin commands: `/stats`, `/queue`, `/play`, `/topup`, `/collection`, `/parameters`
97+
98+
## Architecture Notes
99+
100+
- Bot startup flow: `main.ts` → connect MongoDB → create bot → create server → start subscription → start bot
101+
- Auth uses Telegram's `initData` signature validation (7-day expiry)
102+
- Transaction monitoring polls TON blockchain for incoming wallet transactions
103+
- NFT minting pipeline: select image → AI generation (Stability) → IPFS upload (Pinata) → on-chain mint
104+
- Claim system: 60s cooldown, 10-day max streak, 100 base reward with multiplier
105+
106+
## Current State & Known Issues
107+
108+
- **TODOs in code:**
109+
- `src/bot/features/play.ts:41` — Story game lacks conversation persistence in DB
110+
- `src/common/helpers/telegram.ts:114` — User activity tracking logic incomplete
111+
- `src/bot/features/admin/queue.ts:244` — `sendNewPlaces` notification commented out
112+
- **Test coverage:** Auth, claim, wallet, balances, leaderboard handlers tested. NFT handler untested.
113+
- **Error handling:** NFT handler returns plain objects without proper HTTP status codes.
114+
- **Hidden routes:** `/cnft`, `/faq`, `/clicker` exist but are not shown in navigation menu.
115+
116+
## When Making Changes
117+
118+
- **Backend handler changes:** Check corresponding test file, run `npm run test:backend`
119+
- **Model changes:** Check all handlers and helpers that reference the model
120+
- **Frontend changes:** Stay within `src/frontend/` subtree
121+
- **Config changes:** Update both `src/config.ts` and `.env.example`
122+
- **Bot feature changes:** Check `src/bot/index.ts` for feature registration order
123+
- Always run `npm run lint` and `npm run typecheck` before considering work done

‎CODEX.md‎

Lines changed: 38 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -14,14 +14,44 @@ Help contributors and automation tools work effectively in this repo by providin
1414
- Prefer TypeScript edits under `src/`.
1515
- Avoid changing generated or built assets under `build/` unless requested.
1616
- Keep ESM import style (no CommonJS `require`).
17+
- Frontend (`src/frontend/`) is a separate package — keep deps isolated.
18+
- No semicolons, single quotes, 2-space indent (Prettier enforced).
1719

18-
## When In Doubt
19-
- Check `src/main.ts` for bot startup and wiring.
20-
- Check `src/server.ts` for HTTP server behavior.
21-
- Check `src/frontend/src` for UI flows and API calls.
20+
## Key Entry Points
21+
- `src/main.ts` — Bot startup, MongoDB connection, server wiring
22+
- `src/server.ts` — HTTP server, API routes, static files
23+
- `src/bot/index.ts` — Bot middleware chain and feature registration
24+
- `src/config.ts` — Environment configuration (znv + zod)
25+
- `src/frontend/src/router/index.ts` — Frontend routes
26+
- `src/frontend/src/stores/userStore.ts` — Frontend state (Pinia)
27+
28+
## Data Models
29+
All Typegoose models live in `src/common/models/`:
30+
- **User** — Telegram user profile, wallet, game state, votes
31+
- **Balance** — Balance change history (deposit, withdraw, claim, dice, etc.)
32+
- **Claim** — Daily claim streaks and rewards
33+
- **CNFT** — Compressed NFT metadata and types
34+
- **Transaction** — TON blockchain transaction records
35+
- **Vote** — Referral tracking
36+
37+
## API Routes (under `/api/`)
38+
- `POST /api/auth/login` — Telegram initData auth
39+
- `POST /api/auth/set-wallet` — Store TON wallet
40+
- `POST /api/captcha` — Bot captcha
41+
- `GET /api/nft/:index` — NFT metadata + images
42+
- `GET /api/users/balance` — User balance
43+
- `GET /api/users/leaderboard` — Ranked leaderboard
44+
- `POST /api/users/claim` — Daily reward claim
2245

2346
## Useful Commands
24-
- `npm run lint`
25-
- `npm run typecheck`
26-
- `npm run format`
27-
- `npm run build:all`
47+
- `npm run lint` — ESLint
48+
- `npm run typecheck` — TypeScript check
49+
- `npm run format` — Prettier
50+
- `npm run test:backend` — Run backend tests (Node.js test runner)
51+
- `npm run build:all` — Build backend + frontend
52+
53+
## Further Reading
54+
- `CLAUDE.md` — Comprehensive project guide for AI agents
55+
- `ARCHITECTURE.md` — System architecture overview
56+
- `AGENTS.md` — Agent-specific orientation guide
57+
- `docs/FUTURE_DEVELOPMENT.md` — Prioritized improvement and feature ideas

0 commit comments

Comments
 (0)