mirror of
https://github.com/xCyanGrizzly/DragonsStash.git
synced 2026-05-10 22:01:16 +00:00
Update tg issues
This commit is contained in:
xCyanGrizzly
102
CLAUDE.md
Normal file
102
CLAUDE.md
Normal file
@@ -0,0 +1,102 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Project Overview
|
||||
|
||||
Dragon's Stash is a self-hosted inventory management system for 3D printing filament, SLA resin, miniature paints, and supplies. It includes an integrated Telegram archive worker that scans channels for ZIP/RAR archives, indexes their contents, and a bot that lets users search and receive packages via Telegram.
|
||||
|
||||
## Tech Stack
|
||||
|
||||
- **App**: Next.js 16 (App Router), TypeScript 5.9 (strict), Tailwind CSS 4, shadcn/ui
|
||||
- **Database**: PostgreSQL 16+ via Prisma v7.4 with `@prisma/adapter-pg`
|
||||
- **Auth**: Auth.js v5 (NextAuth) with credentials + optional GitHub OAuth
|
||||
- **Worker**: TypeScript + TDLib (via `tdl`) for Telegram channel scanning
|
||||
- **Bot**: TypeScript + TDLib for Telegram bot interface
|
||||
- **Forms**: React Hook Form + Zod v4
|
||||
|
||||
## Commands
|
||||
|
||||
### App (root package.json)
|
||||
```bash
|
||||
npm run dev # Next.js dev server with hot reload
|
||||
npm run build # Production build (standalone output)
|
||||
npm run start # Production server
|
||||
npm run lint # ESLint (next/core-web-vitals + TypeScript)
|
||||
```
|
||||
|
||||
### Database
|
||||
```bash
|
||||
npm run db:generate # Generate Prisma client
|
||||
npm run db:migrate # Run migrations (dev mode)
|
||||
npm run db:push # Push schema without migrations
|
||||
npm run db:seed # Seed database with test data
|
||||
npm run db:studio # Prisma Studio UI
|
||||
npx prisma migrate dev --name <description> # Create new migration
|
||||
```
|
||||
|
||||
### Worker & Bot (each in their own directory)
|
||||
```bash
|
||||
cd worker && npm run dev # Dev mode with tsx watch
|
||||
cd worker && npm run build # TypeScript compile to dist/
|
||||
cd bot && npm run dev # Dev mode with tsx watch
|
||||
cd bot && npm run build # TypeScript compile to dist/
|
||||
```
|
||||
|
||||
### Dev Environment Setup
|
||||
```bash
|
||||
docker compose -f docker-compose.dev.yml up -d # Start PostgreSQL + worker
|
||||
npm run dev # Run app locally
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
### Three-Service Design
|
||||
The project is split into three independent services sharing one PostgreSQL database:
|
||||
1. **App** (root `src/`): Next.js web UI for inventory management and Telegram admin
|
||||
2. **Worker** (`worker/`): Scans Telegram source channels, processes archives, uploads to destination channel
|
||||
3. **Bot** (`bot/`): Telegram bot for user search, package delivery, keyword subscriptions
|
||||
|
||||
Services communicate asynchronously via `pg_notify` (e.g., on-demand channel fetches, bot send requests).
|
||||
|
||||
### App Source Layout (`src/`)
|
||||
- `app/(auth)/` — Login/register pages (public)
|
||||
- `app/(app)/` — Protected routes behind auth middleware (dashboard, filaments, resins, paints, supplies, vendors, locations, settings, stls, telegram, usage)
|
||||
- `app/api/` — API routes (NextAuth, health check, bot endpoints)
|
||||
- `data/` — Server-side Prisma query functions (`*.queries.ts`), one file per domain model
|
||||
- `schemas/` — Zod validation schemas, one file per domain model
|
||||
- `components/ui/` — shadcn/ui primitives
|
||||
- `components/shared/` — Reusable business components (data-table, status-badge, color-swatch, stat-card, page-header)
|
||||
- `components/layout/` — Sidebar and header
|
||||
- `lib/` — Auth config, Prisma singleton, constants, utilities, Telegram query helpers
|
||||
- `hooks/` — Custom React hooks (use-modal, use-debounce, use-current-user)
|
||||
- `types/` — Shared TypeScript types
|
||||
|
||||
### Key Patterns
|
||||
- **Server Components by default** — pages are async server components that fetch data directly. Only interactive components use `"use client"`.
|
||||
- **Server Actions for mutations** — each page directory has an `actions.ts` file with create/update/delete actions.
|
||||
- **Data queries centralized** — all Prisma reads go through `src/data/*.queries.ts`, not inline in components.
|
||||
- **Modal-based CRUD** — add/edit forms use dialog modals, not separate pages.
|
||||
- **TanStack Table** with server-side pagination for all inventory tables.
|
||||
- **All Prisma PKs use `cuid()`** string IDs.
|
||||
|
||||
### Worker Pipeline
|
||||
1. Authenticate Telegram account via TDLib (SMS code flow, managed via admin UI)
|
||||
2. Scan source channels for messages since `lastProcessedMessageId`
|
||||
3. Detect archives (ZIP/RAR), group multipart sets, extract file listings
|
||||
4. Hash for dedup, match preview images, extract creator from filename
|
||||
5. Split files >2GB, upload to destination channel, track progress
|
||||
|
||||
### ESLint Scope
|
||||
ESLint covers `src/` only. The `worker/`, `bot/`, `scripts/`, and `prisma/seed.ts` directories are excluded from linting.
|
||||
|
||||
## Docker Deployment
|
||||
|
||||
- `docker-compose.yml` — Production: app + worker + bot + db
|
||||
- `docker-compose.dev.yml` — Dev: db + worker only (app runs locally)
|
||||
- `docker-entrypoint.sh` — Runs migrations, optional seeding, then starts app
|
||||
- Bot service uses Docker Compose profiles (`bot` or `full`) — not started by default
|
||||
|
||||
## Testing
|
||||
|
||||
No test framework is configured. Testing is manual.
|
||||
Reference in New Issue
Block a user