{"id":15962824,"url":"https://github.com/virtyaluk/tg_cinemacity_app","last_synced_at":"2026-04-11T17:04:35.277Z","repository":{"id":199564878,"uuid":"702306577","full_name":"virtyaluk/tg_cinemacity_app","owner":"virtyaluk","description":"Skip the line and watch new movies as soon as they hit theaters with the Cinema City Telegram App.","archived":false,"fork":false,"pushed_at":"2023-10-11T06:59:10.000Z","size":819,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-29T11:52:20.343Z","etag":null,"topics":["bot","expressjs","nodejs","react","sass","telegraf","telegram","telegram-miniapp-contest-2023"],"latest_commit_sha":null,"homepage":"https://t.me/CinemaCityAppBot","language":"TypeScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/virtyaluk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-09T04:05:55.000Z","updated_at":"2023-10-24T06:03:42.000Z","dependencies_parsed_at":"2024-10-30T02:02:59.550Z","dependency_job_id":null,"html_url":"https://github.com/virtyaluk/tg_cinemacity_app","commit_stats":null,"previous_names":["virtyaluk/tg_cinemacity_app"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/virtyaluk%2Ftg_cinemacity_app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/virtyaluk%2Ftg_cinemacity_app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/virtyaluk%2Ftg_cinemacity_app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/virtyaluk%2Ftg_cinemacity_app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/virtyaluk","download_url":"https://codeload.github.com/virtyaluk/tg_cinemacity_app/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247176736,"owners_count":20896521,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bot","expressjs","nodejs","react","sass","telegraf","telegram","telegram-miniapp-contest-2023"],"created_at":"2024-10-07T16:21:08.779Z","updated_at":"2026-04-11T17:04:35.232Z","avatar_url":"https://github.com/virtyaluk.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cinema City Telegram Mini App\n\nThis is a demonstration app that utilizes Telegram features like [Bot API](https://core.telegram.org/bots/api), [Mini Apps](https://core.telegram.org/bots/webapps#initializing-mini-apps), [Payments API](https://core.telegram.org/bots/payments), and [The Movies DataBase](https://www.themoviedb.org/) API to build a ticket application for a fictional cinema called Cinema City.\n\n\u003e [@CinemaCityAppBot](https://t.me/CinemaCityAppBot) is the only mobile movie ticketing app that lets you buy movie tickets, make movie plans with friends \u0026 get a VIP experience at the theater so you never wait in line. When you get to the movie theater, skip the box office line \u0026 scan your digital movie ticket with your phone.\n\n![app presentation](https://github.com/virtyaluk/tg_cinemacity_app/assets/795984/1db89826-6205-444c-9975-626a7b90b000)\n\nSome of the app features include:\n- a nice responsive UI with the support of Telegram's [dynamic color schema change](https://core.telegram.org/bots/webapps#themeparams);\n- builtin multi-language support for the client application;\n- seamless payment process using Telegram's [Payments API](https://core.telegram.org/bots/payments);\n- use of the [CloudStorage](https://core.telegram.org/bots/webapps#cloudstorage) API to store the app configs;\n- [haptic feedback](https://core.telegram.org/bots/webapps#hapticfeedback) to make the user's experience even funnier.\n\nThe app is built using [TypeScript](https://www.typescriptlang.org/), [Node.js](https://nodejs.org/en), [React](https://react.dev/), [telegraf](https://github.com/telegraf/telegraf), and [Express](https://expressjs.com/).\n\n## Getting started\n\nBefore you start, make sure you have everything you may need to build and run the app.\n\nFor this project, you have to have `Node.js` version 17 and `yarn` package manager installed on your system.\n\nYou may want to try [nvm](https://github.com/nvm-sh/nvm) to manage Node installations in your system:\n\n```shell\n$ nvm install v17\n\n$ node --version\nv17.9.1\n\n$ npm --version\n8.11.0\n```\nInstall [yarn](https://yarnpkg.com/):\n\n```shell\n$ npm i -g yarn\n$ yarn --version\n1.22.19\n```\n\nThis is all you need to build the project.\n\n## Building the project\n\nClone the project's repo:\n\n```shell\n$ git clone git@github.com:virtyaluk/tg_cinemacity_app.git\n$ cd ./tg_cinemacity_app\n```\n\nThe project root contains a separate dir for each client and server side of the app. Make sure you installed Node dependencies for both client, server, and main tools.\n\nFrom the root of the repo execute the following:\n\n```shell\n$ yarn install\n```\n\nThen do the same for the server part:\n\n```shell\n$ cd ./server\n$ yarn install\n$ cd ../\n```\n\nand the client part:\n\n```shell\n$ cd ./client\n$ yarn install\n$ cd ../\n\n```\nThen the only thing left us to build the project:\n\n```shell\n$ yran build\n```\n\nCongrats! You're ready to run the thing up.\n\n## Before running the project\n\nBefore you run the project, there are two things that you have to take care of beforehand: server certificates and the `.env` file containing your Telegram bot tokens.\n\n### Server certificates\n\nTelegram puts very strong rules on your Mini App and disallows to use of non-secure sources for the app. Thus, you have to run your app by means of HTTPS. This is already implemented in the given app so the only thing you are left with is to provide your own SSL certificate. The certs must be placed inside `./server/certs/` dir.\n\nIn my case, I'm using free [Let's Encrypt](https://letsencrypt.org/) certificates for my personal domain. You could use [certbot](https://tecadmin.net/how-to-generate-lets-encrypt-ssl-using-certbot/) to generate free certificates for your domain.\n\nOr, if you are only going to run this app locally, use these commands to generate self-signed certificates:\n\n```shell\n# Generate private key\n$ openssl genrsa -out key.pem\n\n# Create Certificate Signing Request\n$ openssl req -new -key key.pem -out csr.pem\n\n# Generate the SSL certificate\nopenssl x509 -req -days 365 -in csr.pem -signkey key.pem -out cert.pem\n```\n\nMake sure you have both `cert.pem` and `key.pem` in your server's `certs` dir:\n\n```shell\n$ ls ./server/certs\ncert.pem  key.pem\n```\n\n### .env file\n\nMake sure to update `.env` file in the root of the server folder with your Telegram bot configuration and TMDb access token.\n\nFor the Telegram part, you need to create your custom bot by means of [@BotFather](https://t.me/botfather) and set up a payment provider for the newly created bot which will yield you tokens for the bot itself and for the payments API.\n\nUse the following guides to get the relevant tokens:\n\n- [Telegram Bots \u003e From BotFather to 'Hello World'](https://core.telegram.org/bots/tutorial#obtain-your-bot-token)\n- [Bot Payments API \u003e Connecting Payments](https://core.telegram.org/bots/payments#connecting-payments)\n\nSince this app relies on data from The Movie Database, you have to obtain a separate set of tokens for the TMDb API:\n\n- [Get started with the basics of the TMDB API](https://developer.themoviedb.org/docs)\n\nYour `.env` file should look like this now:\n\n```dotenv\nTMDB_API_KEY=\"your_tmdb_api_key\"\nTMDB_ACCESS_TOKEN=\"your_tmdb_access_token\"\nBOT_TOKEN=\"your_bot_token\"\nPROVIDER_TOKEN=\"your_provider_token\"\n```\n\nAnd you're finally good to go.\n\n## Running the project\n\n### dev mode\n\nTo run the project in `development` mode, do this:\n\n```shell\n$ yarn start:dev\n```\n\nThis will bring up your server on a separate port (`4000`, by default) and will continue to watch any code changes to apply them live.\n\nIt will also run the frontend as a separate instance on port `8080` with the support of hot reloading.\n\nThis running mode is suitable for local development and debugging.\n\n**NOTE:** *Sometimes, the dev server fails to release port listeners upon the close making it impossible to restart the application backend. In this case, you need to find a dangling process sitting on the locked port and kill it.*\n\n### prod mode\n\nThe `production` server will create a single process for both the client and the server:\n\n```shell\n$ yarn start \n```\n\n## Debugging\n\nGiven that the Telegram Mini App web script isn't of any use while running locally, to lighten the burden of application debugging the app code exposes a couple of helper functions as the properties on the global `window` object:\n- a call to the `window.TgApp.mainBtnClickHandler` simulates a click on the main button and executes any handler you happen to assign using [`WebApp.MainButton.onClick`](https://core.telegram.org/bots/webapps#mainbutton)\n- while `window.tgApp.backBtnClickHandler` does the same but for the Back button. \n\n## The project structure\n\nThe project is split into two components - the server part and the client part.\n\n### Server\n\n```shell\n\n├── server\n│   ├── certs\n│   └── src\n│       ├── config\n│       ├── middleware\n│       ├── models\n│       │   └── services\n│       ├── routes\n│       │   └── api\n│       ├── services\n│       ├── types\n│       └── utils\n```\n\n- `certs` is where your SSL certs go.\n- `src/config` is for the dev/prod server configuration.\n- `src/middleware` isn't really used.\n- `src/models` is where all custom types and interfaces for the server entities are stored.\n- `src/routes` is for API routes definition.\n- `src/services` holds a bunch of backend services like the main db service, TMDb service, Telegram Bot service, etc.\n- `src/types` is used to store custom TypeScript type definitions.\n- `src/utils` holds a set of helper functions.\n\n### Client\n\n```shell\n├── client\n│   ├── public\n│   │   └── assets\n│   ├── src\n│   │   ├── api\n│   │   ├── components\n│   │   │   └── placeholders\n│   │   ├── config\n│   │   ├── context\n│   │   ├── hooks\n│   │   ├── locales\n│   │   ├── services\n│   │   ├── utils\n│   │   └── views\n```\n\n- `public` is used to store the app's public assets like index.html, favicon, and static pictures.\n- `src/api` is where the main interactions with server API are happening.\n- `src/components` holds the most of UI components written using React.\n- `src/config` responsible for application configuration. For example, this is the place where the server API base URL is stored for both dev and prod.\n- `src/context` is for custom app contexts available globally through the React runtime.\n- `src/hooks` is for custom React hooks.\n- `src/locales` is the place where translated strings for the app are stored. Currently, English and Ukrainian are supported.\n- `src/services` is for a set of application services like a wrapper for the Telegram WebApp component.\n- `src/utils` holds a set of helper functions.\n- `src/views` stores main application views (i.e. screens).\n\n\n## :green_book: License\n\nLicensed under the MIT License.\n\nCopyright (c) 2023 Bohdan Shtepan\n\n---\n\n\u003e [shtepan.com](http://shtepan.com) \u0026nbsp;\u0026middot;\u0026nbsp;\n\u003e [modern-dev.com](http://modern-dev.com) \u0026nbsp;\u0026middot;\u0026nbsp;\n\u003e GitHub [@virtyaluk](https://github.com/virtyaluk)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvirtyaluk%2Ftg_cinemacity_app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvirtyaluk%2Ftg_cinemacity_app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvirtyaluk%2Ftg_cinemacity_app/lists"}