diff --git a/.github/workflows/webpack.yml b/.github/workflows/webpack.yml new file mode 100644 index 0000000..9626ff6 --- /dev/null +++ b/.github/workflows/webpack.yml @@ -0,0 +1,28 @@ +name: NodeJS with Webpack + +on: + push: + branches: [ "main" ] + pull_request: + branches: [ "main" ] + +jobs: + build: + runs-on: ubuntu-latest + + strategy: + matrix: + node-version: [18.x, 20.x, 22.x] + + steps: + - uses: actions/checkout@v4 + + - name: Use Node.js ${{ matrix.node-version }} + uses: actions/setup-node@v4 + with: + node-version: ${{ matrix.node-version }} + + - name: Build + run: | + npm install + npx webpack diff --git a/README.md b/README.md new file mode 100644 index 0000000..7426688 --- /dev/null +++ b/README.md @@ -0,0 +1,238 @@ +Telegram Community & Operations PlatformA Telegram-first community and operations platform for managing assets, files, and group interactions at scale. Built with **GramIO**, **Cloudflare Workers**, **Cloudflare D1**, and **Telegram storage**.- Bot commands for uploads, downloads, and moderation. +- Mini App for in-chat asset management and file browsing. +- Shareable links for public or protected file access. +- Edge-hosted runtime with durable metadata and global media delivery. + +> “Production-ready” refers to the architecture and implementation being designed for robust operation. Full production readiness additionally depends on operational practices such as monitoring, backups, testing, CI/CD, deployment strategy, logging, and secret management. + +--- + +## Project Overview + +This platform treats **Telegram as the primary binary store** and **Cloudflare as the execution and acceleration layer**: + +- **Cloudflare Worker (GramIO)** handles: + - Bot updates and API interactions. + - HTTP APIs for the Mini App and share links. + - Authentication, routing, and business logic. + +- **Cloudflare D1** stores: + - Users, communities, permissions. + - Asset metadata (filename, size, MIME type, Telegram references). + - Indexes for search, listing, and audit. + +- **Telegram** stores: + - All binary media (images, videos, documents, archives, PDFs, audio). + - Long-term, durable object storage via channels or designated chats. + +- **Cloudflare Cache**: + - Edge-caches frequently accessed files. + - Reduces repeated Telegram downloads and improves latency. + +The result is a modular, scalable, and maintainable foundation for community-driven file management and operations. + +--- + +## Features + +- **Telegram Bot** + - Upload and download commands. + - Moderation and community management. + - Notification and broadcast support. + +- **Telegram Mini App** + - Asset manager and file browser inside Telegram. + - Drag-and-drop uploads. + - Per-asset metadata and access controls. + +- **Share Links** + - Public or protected URLs for individual assets. + - Optional expiration, rate limiting, and access rules. + +- **Edge Runtime** + - Cloudflare Worker with GramIO for Telegram update handling. + - Unified middleware pipeline (auth, audit, analytics). + - Feature modules for dashboard, community, support, content, and broadcast. + +- **Storage & Caching** + - D1 for relational metadata and indexes. + - Telegram for permanent binary storage. + - Cloudflare Cache for fast, global file delivery. + +--- + +## High-Level Architecture + +```text + Client ─────┐ + │ +Telegram Bot ─────┤ + │ +Telegram Mini App ├───────────────┐ + │ │ +Share Links ──────┘ │ + ▼ + Cloudflare Worker (GramIO) + │ + ┌─────────────────────────┼─────────────────────────┐ + │ │ │ + ▼ ▼ ▼ + Cloudflare D1 Telegram API Cloudflare Cache + (Metadata & Index) (Primary Object Store) (Edge Cache API) + │ │ ▲ + │ ▼ │ + │ Telegram Channel │ + │ (Binary Source of Truth) │ + │ │ │ + └────────────── File References ────────────────────┘ +``` + +**Component responsibilities** + +| Component | Responsibility | +|----------------------------|-----------------------------------------------------| +| Client | Web UI / browser | +| Telegram Bot | Commands, uploads, downloads | +| Telegram Mini App | Asset manager, file browser | +| Share Links | Public file access | +| Cloudflare Worker (GramIO) | Runtime, authentication, routing, API | +| Cloudflare D1 | Metadata, users, permissions, indexes | +| Telegram | Permanent binary object storage | +| Cloudflare Cache | Edge caching for fast downloads | + +See **[docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md)** for detailed data flows, upload/download sequences, and design rationale. + +--- + +## Quick Start + +1. **Clone the repository** + + ```bash + git clone + cd + ``` + +2. **Install dependencies** (if using a package manager for your stack). + +3. **Create environment file** + + ```bash + cp .env.example .env + ``` + + At minimum, configure: + + ```env + BOT_TOKEN=your_bot_token_from_botfather + WEBHOOK_SECRET=your_webhook_secret + TELEGRAM_STORAGE_CHAT_ID=chat_id_for_media_storage + D1_DATABASE_ID=your_d1_database_id + ENVIRONMENT=development + ``` + +4. **Initialize D1 schema** + + Run the provided SQL migrations (e.g. via `wrangler d1 execute`): + + ```bash + wrangler d1 execute --file=db/schema.sql + ``` + +5. **Run locally** + + - Start the Worker in dev mode (example with Wrangler): + + ```bash + wrangler dev + ``` + + - Configure a local webhook tunnel (e.g. ngrok, Cloudflare Tunnel) and call Telegram’s `setWebhook` with your tunnel URL and `WEBHOOK_SECRET`. + +6. **Test the bot** + + - Open your bot in Telegram. + - Try upload/download commands or open the Mini App. + +See **[docs/LOCAL_DEVELOPMENT.md](./docs/LOCAL_DEVELOPMENT.md)** for more detailed setup instructions, example commands, and troubleshooting. + +--- + +## Deployment + +1. **Provision infrastructure** + + - Create a Cloudflare Worker. + - Create a D1 database and apply migrations. + - Optionally configure KV, Queues, and Cache Rules as needed. + +2. **Set environment variables on the host** + + - `BOT_TOKEN` + - `WEBHOOK_SECRET` + - `TELEGRAM_STORAGE_CHAT_ID` + - `D1_DATABASE_ID` + - `ENVIRONMENT=production` + - Any additional runtime variables. + +3. **Deploy the Worker** + + Example with Wrangler: + + ```bash + wrangler deploy + ``` + +4. **Register the Telegram webhook** + + - Use Telegram’s `setWebhook` API with: + - Your public HTTPS Worker URL. + - The configured `WEBHOOK_SECRET`. + +5. **Verify operation** + + - Send test messages/commands to the bot. + - Upload a file via Bot or Mini App and confirm it appears in D1 and Telegram. + - Access a share link and confirm caching behavior. + +See **[docs/DEPLOYMENT.md](./docs/DEPLOYMENT.md)** for step-by-step deployment guides, environment-specific notes, and operational checklists. + +--- + +## Documentation + +- **[Architecture](./docs/ARCHITECTURE.md)** + Detailed diagrams, data model, upload/download flows, and design rationale. + +- **[Local Development](./docs/LOCAL_DEVELOPMENT.md)** + Environment setup, D1 migrations, running the Worker locally, and debugging. + +- **[Deployment](./docs/DEPLOYMENT.md)** + Production deployment patterns, CI/CD integration, and rollout strategies. + +- **[Health & Telemetry](./docs/HEALTH_AND_TELEMETRY.md)** + `/api/health` endpoint, telemetry counters, and Update Inspector. + +- **[Bot & Mini App](./docs/BOT_AND_MINI_APP.md)** + Commands, Mini App screens, and integration points. + +- **[Operations](./docs/OPERATIONS.md)** + Monitoring, backups, scaling, and incident response playbooks. + +--- + +## License + +Add your preferred license here (e.g. MIT, Apache-2.0). + +--- + +## Contributing + +- Open issues for bugs, feature requests, and questions. +- Use feature branches and pull requests. +- Follow existing module boundaries (bot, worker, D1, Telegram, cache). +- See **[docs/CONTRIBUTING.md](./docs/CONTRIBUTING.md)** for contribution guidelines. +``` + +If you share your repo name and preferred license, I can customize the header and add badges (e.g., Cloudflare Workers, D1, GramIO, Telegram Bot API).