# openbuilders/contest-tool architecture

> Architecture diagram of the GitHub repository openbuilders/contest-tool, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openbuilders/contest-tool
- Repository: https://github.com/openbuilders/contest-tool

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Hosting
    CDN["Static Hosting/CDN"]:::external
    FE["Frontend (SolidJS Mini-App)"]:::frontend
    CDN -->|"serves static assets"| FE

    %% Backend Service Layers
    subgraph "Backend Service"
        API["API Endpoints"]:::backend
        BL["Business Logic"]:::backend
        DAL["Data Access Layer"]:::backend
        EI["External Integrations"]:::backend
    end

    %% Data Store
    DB["Database"]:::data

    %% External Services
    TB["Telegram Bot API"]:::external
    TON["TON Blockchain (Optional)"]:::external

    %% Data Flows
    FE -->|"HTTPS"| API
    API -->|"routes to"| BL
    BL -->|"queries"| DAL
    DAL -->|"reads/writes (SQL)"| DB
    BL -->|"calls"| EI
    EI -->|"webhook/polling"| TB
    EI -->|"transactions"| TON

    %% Documentation Site
    subgraph "Docs (VitePress)"
        DocsIndex["docs/index.md"]:::docs
        DocsIntro["docs/intro.md"]:::docs
        BackendSetup["docs/backend/setup.md"]:::docs
        BackendStack["docs/backend/stack.md"]:::docs
        FrontendSetup["docs/frontend/setup.md"]:::docs
        FrontendStack["docs/frontend/stack.md"]:::docs
        ViteConfig["docs/.vitepress/config.ts"]:::docs
        DocsPkg["docs/package.json"]:::docs
        DocsTS["docs/tsconfig.json"]:::docs
    end

    %% Click Events
    click FE "https://github.com/openbuilders/contest-tool/tree/master/app/"
    click API "https://github.com/openbuilders/contest-tool/tree/master/backend/"
    click BL "https://github.com/openbuilders/contest-tool/tree/master/backend/"
    click DAL "https://github.com/openbuilders/contest-tool/tree/master/backend/"
    click EI "https://github.com/openbuilders/contest-tool/tree/master/backend/"
    click CDN "https://github.com/openbuilders/contest-tool/tree/master/backend/"
    click DocsIndex "https://github.com/openbuilders/contest-tool/blob/master/docs/index.md"
    click DocsIntro "https://github.com/openbuilders/contest-tool/blob/master/docs/intro.md"
    click BackendSetup "https://github.com/openbuilders/contest-tool/blob/master/docs/backend/setup.md"
    click BackendStack "https://github.com/openbuilders/contest-tool/blob/master/docs/backend/stack.md"
    click FrontendSetup "https://github.com/openbuilders/contest-tool/blob/master/docs/frontend/setup.md"
    click FrontendStack "https://github.com/openbuilders/contest-tool/blob/master/docs/frontend/stack.md"
    click ViteConfig "https://github.com/openbuilders/contest-tool/blob/master/docs/.vitepress/config.ts"
    click DocsPkg "https://github.com/openbuilders/contest-tool/blob/master/docs/package.json"
    click DocsTS "https://github.com/openbuilders/contest-tool/blob/master/docs/tsconfig.json"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef backend fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef data fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef external fill:#D8BFD8,stroke:#333,stroke-width:1px;
    classDef docs fill:#D3D3D3,stroke:#333,stroke-width:1px;
```
