How openbuilders/contest-tool works
Project Type & Purpose
• This is a full-stack Telegram-integrated contest platform (“Contests Tool”) with:
• A SolidJS-based web Mini-App frontend (in the top-level app/ folder)
• A TypeScript + Bun backend service (in backend/)
• Deep integration with the Telegram Bot API (for contest entry, moderation, notifications)
• Persistence and optional TON-blockchain payments
File Structure
• Top-level directories:
• app/ – SolidJS frontend code, Vite configs, static assets
• backend/ – Bun server entry points, API routes, business logic, data access
• docs/ – VitePress documentation site (not part of runtime)
• Config & build files:
• Bun lockfile (docs/bun.lock) and package.json under docs/ for docs site
• Likely package.json and tsconfig.json exist within app/ and backend/ but are omitted here
• No separate microservices folder — it’s a monolithic backend process that handles both HTTP API and Telegram webhooks.
Key Insights from README
• Features: anonymous participation, flexible contest creation, theming, trusted moderation
• Tech Stack: SolidJS, Vite (frontend), Bun + TypeScript (backend), Docker supported for backend
• External integrations: Telegram Bot API, potentially TON blockchain for entry fees
Main Components & Their Relationships
A. Frontend (SolidJS Mini-App)
• Served as static assets (HTML/CSS/JS) from a CDN or Bun static middleware
• Communicates via HTTPS to Backend API for contest data, user actions
B. Backend Service (TypeScript + Bun)
• Exposes REST (or GraphQL) API endpoints for the frontend
• Hosts Telegram Bot webhook handler (receives updates, routes commands)
• Contains business logic modules: Contest Manager, User/Session Manager, Moderation, Rewards
• Data Access layer interfaces with a Database (e.g. PostgreSQL) and optionally object storage
• External integration modules: Telegram Bot API client, TON-chain client
C. Database
• Stores Users, Contests, Entries, Moderation actions, Anonymized identity mappings
D. External Services
• Telegram Bot API (webhook or long-polling)
• TON blockchain (for contest entry payments)
• Frontend → Backend API calls
• Backend → Database reads/writes
• Backend ↔ Telegram Bot API
• Backend → TON blockchain (for payment transactions)
• Frontend ← Static hosting/CDN
Architectural Patterns & Design Principles
• Layered monolith on the backend:
1. API Layer
2. Business Logic Layer (contest rules, anonymity enforcement)
3. Data Access Layer
4. External Integrations
• Separation of concerns: UI, API, data store, external systems
• Use of webhooks or polling for Telegram integration
• Containerization (Docker) for deployment consistency
• Static site generation (SSG) for docs via VitePress in docs/
Technologies, Frameworks & Libraries
• Frontend: SolidJS, Vite, TypeScript, CSS framework (if any)
• Backend: Bun runtime, TypeScript, Express-style router or Bun’s built-in, Docker
• Database: PostgreSQL (or your chosen SQL/NoSQL)
• External SDKs: Telegram Bot API client, TON client SDK
• Dev tooling: ESLint, Prettier, Bun scripts, VitePress