Cinema Hikes

A clean, modular platform for discovering and watching movies online, with a Telegram-based download workflow.

Cinema Hikes is a team academic project built around ASP.NET Core, React, PostgreSQL and Clean Architecture. The project is designed to provide a modern movie catalogue, online playback, user accounts, reviews, favourites, viewing history, administration and a Telegram bot for movie search and downloading.

The repository contains the project requirements, architectural specification and implementation skeleton. The documentation deliberately distinguishes the target product defined by the SRS from the functionality currently present in the repository.

Project goals

Cinema Hikes addresses a familiar problem: movie catalogues often combine a fragmented user experience, intrusive advertising, unreliable video sources and inconvenient access to alternative sources.

The project aims to provide:

a clean, responsive movie catalogue;
search, filtering and pagination;
online movie playback without injecting advertising into the client experience;
multiple video sources for a movie;
authentication and a personal user area;
favourites, viewing history and reviews;
an administration area for catalogue and source management;
a Telegram bot for movie search and downloading;
automated retrieval and revalidation of external video links;
a maintainable architecture suitable for further development and academic demonstration.

Features

Catalogue

Movie catalogue with pagination.
Search by movie title.
Filtering by genre, release year and rating.
Movie details with poster, titles, year, genres and rating.
Multiple video sources for the same movie.
Video-quality model supporting 360p, 480p, 720p and 1080p.

User account

Registration and login.
JWT-based authentication.
ASP.NET Core Identity.
Favourites.
Viewing history and playback progress.
Movie reviews and ratings.

Administration

The target architecture includes dedicated administration services and API controllers for:

movie CRUD;
genres;
video sources;
users and roles;
review moderation;
analytics.

Telegram bot

The target product includes a separate Telegram bot application with:

text-based movie search;
interactive movie selection;
quality selection;
direct video delivery when the file is within Telegram limits;
direct-link fallback for larger files;
in-memory rate limiting.

External video sources

The architecture isolates source-specific browser automation behind ports and adapters. Playwright-based infrastructure can open a source page, interact with its player and extract a direct video URL for the requested quality.

A background job is intended to revalidate stored movie links so that stale external URLs can be refreshed.

Content and legal responsibility: external video sources are outside this repository. Deployment and use of the platform must comply with applicable copyright, licensing, privacy and other laws.

Technology stack

Area Technology

Backend ASP.NET Core / .NET 10

Language C#

Architecture Clean Architecture, SOLID, repository and unit-of-work abstractions

ORM Entity Framework Core 10

Database PostgreSQL 16

Authentication ASP.NET Core Identity + JWT

Browser automation Microsoft Playwright

Telegram Telegram Bot API / Telegram.Bot

Frontend React 19 + TypeScript

Frontend tooling Vite 8

UI Ant Design 6

Client state Zustand

HTTP Axios

Routing React Router

API description OpenAPI

Containers Docker / Docker Compose

Testing NUnit, with unit and integration-test projects planned in the solution

Architecture overview

The backend follows Clean Architecture. Dependencies point inward: the domain contains business concepts and contracts, while infrastructure contains implementation details.

                         ┌──────────────────────────┐
                         │        React SPA         │
                         │ React + TypeScript +     │
                         │ Ant Design + Axios       │
                         └────────────┬─────────────┘
                                      │ HTTP / JWT
                                      ▼
                         ┌──────────────────────────┐
                         │     CinemaHikes.WebApi   │
                         │ Controllers / Middleware │
                         └────────────┬─────────────┘
                                      │
                                      ▼
                         ┌──────────────────────────┐
                         │ CinemaHikes.Application  │
                         │ Services / DTOs /        │
                         │ Validators / Mappings    │
                         └────────────┬─────────────┘
                                      │
                                      ▼
                         ┌──────────────────────────┐
                         │   CinemaHikes.Domain     │
                         │ Entities / Interfaces /  │
                         │ Specifications / Enums   │
                         └────────────▲─────────────┘
                                      │
                         ┌────────────┴─────────────┐
                         │ CinemaHikes.Infrastructure│
                         │ EF Core / PostgreSQL /   │
                         │ Identity / Playwright /  │
                         │ Telegram / Security      │
                         └──────────────────────────┘

                         ┌──────────────────────────┐
                         │ TelegramBotDownloader    │
                         │ Search → Select →        │
                         │ Download                 │
                         └──────────────────────────┘

Backend projects

CinemaHikes/
├── CinemaHikes.slnx
├── src/
│   ├── CinemaHikes.Domain/
│   ├── CinemaHikes.Application/
│   ├── CinemaHikes.Infrastructure/
│   ├── CinemaHikes.WebApi/
│   └── CinemaHikes.TelegramBotDownloader/
├── frontend/
└── tests/

Domain

CinemaHikes.Domain is the centre of the system. It contains entities such as Movie, Genre, MovieGenre, VideoSource, MovieLink, Review, FavoriteMovie, ViewHistoryEntry and ParsingSourceConfig.

It also defines repository interfaces, service ports, bot abstractions and specifications such as:

MovieFilterSpecification;
MovieSearchSpecification;
ActiveSourcesSpecification.

The domain does not depend on PostgreSQL, Playwright, Telegram or the web framework.

Application

CinemaHikes.Application contains use-case-oriented services and DTOs. The architecture includes services for movies, genres, authentication, favourites, history, reviews, administration, Telegram search and movie downloads.

Validation and object mapping are kept outside the domain entities, allowing the application layer to coordinate use cases without coupling them to infrastructure.

Infrastructure

CinemaHikes.Infrastructure provides implementations for:

Entity Framework Core and PostgreSQL;
ASP.NET Core Identity;
repositories and unit of work;
JWT token generation and current-user access;
Playwright browser automation;
Telegram file delivery;
background link revalidation.

Source-specific browser logic is isolated behind interfaces such as IBrowserFactory, IFilmParserFacade, IFilmUrlParser and IPageElementParser.

Web API

CinemaHikes.WebApi is the HTTP boundary of the application. The target architecture defines controllers for authentication, movies, genres, favourites, history, reviews and administration, together with centralized exception handling.

Frontend

The React application is organized into application infrastructure, layouts, pages, business features and shared components.

frontend/
└── src/
    ├── app/          # providers, router, global state
    ├── layouts/      # main, admin and auth layouts
    ├── pages/        # public, auth, private and admin pages
    ├── features/     # auth, catalogue, movie details, profile, admin
    └── shared/       # API client, types, UI, hooks and utilities

The intended UI uses a dark, Netflix-style visual language with protected routes for authenticated and administrative areas.

Repository structure

cinema-hikes/
├── .example.env
├── docker-compose.yml
├── SRS.md
├── README.md
└── CinemaHikes/
    ├── CinemaHikes.slnx
    ├── docker/
    ├── frontend/
    └── src/
        ├── CinemaHikes.Domain/
        ├── CinemaHikes.Application/
        ├── CinemaHikes.Infrastructure/
        ├── CinemaHikes.WebApi/
        └── CinemaHikes.TelegramBotDownloader/

Prerequisites

Install the following before starting local development:

Git;
.NET 10 SDK;
Node.js and npm compatible with the Vite frontend;
Docker Desktop or Docker Engine with Docker Compose;
a PostgreSQL client, optional but useful for inspection;
Chromium dependencies required by Playwright when browser automation is used;
a Telegram bot token if the Telegram application is being run.

Check the main tools:

dotnet --version
node --version
npm --version
docker --version
docker compose version

Installation

Clone the repository:

git clone https://github.com/n0rtx/cinema-hikes.git
cd cinema-hikes

The backend solution is located in CinemaHikes/:

cd CinemaHikes
dotnet restore CinemaHikes.slnx

Install frontend dependencies:

cd frontend
npm install

Configuration

The repository provides a root .example.env containing PostgreSQL configuration:

POSTGRES_DB=cinemahikes
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_PORT=5432

Create a local .env from the example and replace credentials as appropriate. Do not commit real passwords, tokens or connection strings.

For application secrets, prefer ASP.NET Core User Secrets during local development or environment variables in deployment.

Environment variables

PostgreSQL

Variable Purpose Default in Compose

POSTGRES_DB Database name cinemahikes POSTGRES_USER PostgreSQL user postgres POSTGRES_PASSWORD PostgreSQL password postgres POSTGRES_PORT Host port mapped to PostgreSQL 5432

The exact application connection-string key should follow the configuration expected by the current Infrastructure implementation. Keep credentials outside source control.

Frontend

The architecture specifies:

VITE_API_URL=https://localhost:5001/api

Use the actual API address exposed by your local Web API. Vite only exposes variables prefixed with VITE_ to client-side code, so never put private secrets in frontend environment variables.

When running the Telegram bot, configure its bot token and any source-specific settings through the bot project's supported configuration mechanism. Do not commit the token.

Database setup

Cinema Hikes uses PostgreSQL 16. The repository already provides a Docker Compose service for PostgreSQL with a persistent named volume and a health check.

Start PostgreSQL from the repository root:

docker compose up -d postgres

Verify the container:

docker compose ps

The database is exposed on the configured host port, 5432 by default.

Migrations

The Infrastructure project contains the Entity Framework Core migration area. From the CinemaHikes directory, use the EF Core CLI after restoring the solution and configuring the database connection:

dotnet ef migrations list \
  --project src/CinemaHikes.Infrastructure \
  --startup-project src/CinemaHikes.WebApi

To apply existing migrations:

dotnet ef database update \
  --project src/CinemaHikes.Infrastructure \
  --startup-project src/CinemaHikes.WebApi

To create a new migration after a model change:

dotnet ef migrations add <MigrationName> \
  --project src/CinemaHikes.Infrastructure \
  --startup-project src/CinemaHikes.WebApi

If dotnet ef is not installed globally:

dotnet tool install --global dotnet-ef

Seed data

The SRS requires a usable movie catalogue and multiple external sources, but a dedicated repository-level seed command is not currently documented in the checked-in implementation.

If seed logic is added, keep it idempotent and run it after database migrations. Recommended seed data includes genres, development users/roles and a small set of movies with video-source metadata.

For production deployments, never use development passwords or development-only accounts as seed data.

Running the backend

The Web API project is:

CinemaHikes/src/CinemaHikes.WebApi

Run it from the solution directory:

dotnet run --project src/CinemaHikes.WebApi

For development, ASP.NET Core's OpenAPI endpoint is mapped by the current Web API bootstrap when the environment is Development.

Current repository status: the checked-in Program.cs is still a minimal ASP.NET Core template and currently exposes the sample weatherforecast endpoint. The full controller/application pipeline described in the SRS and architecture document is therefore the target architecture, not yet a complete reflected implementation in the current branch.

Running the frontend

cd CinemaHikes/frontend
npm install
npm run dev

Vite will print the local development URL in the terminal.

For a production build:

npm run build
npm run preview

The frontend package currently provides dev, build, lint and preview scripts.

Running tests

The architecture defines four test projects:

tests/
├── CinemaHikes.Domain.UnitTests/
├── CinemaHikes.Application.UnitTests/
├── CinemaHikes.WebApi.IntegrationTests/
└── CinemaHikes.TelegramBot.IntegrationTests/

Run the complete test suite when the test projects are present in the current checkout:

dotnet test CinemaHikes.slnx

Frontend linting:

cd CinemaHikes/frontend
npm run lint

The SRS identifies NUnit and Playwright as the intended testing technologies. The test projects should be treated as part of the acceptance and regression strategy rather than as an optional add-on.

Docker

Docker Compose is currently used for PostgreSQL infrastructure.

Start the database:

docker compose up -d postgres

Stop it:

docker compose down

Stop it and remove the persistent database volume:

docker compose down -v

The Compose file uses:

postgres:16-alpine

and persists data in the cinemahikes_pgdata named volume.

The repository also contains a CinemaHikes/docker/ directory for project-specific container assets. Full application-container orchestration should only be documented here once corresponding Dockerfiles and services are present in the branch.

API documentation

OpenAPI

The current Web API project uses ASP.NET Core's OpenAPI support through Microsoft.AspNetCore.OpenApi and AddOpenApi().

In Development, the OpenAPI document is exposed by MapOpenApi().

Scalar

The requested project documentation includes Scalar as the API explorer. The current checked-in Program.cs, however, does not yet register Scalar. Once Scalar is added, the recommended local route is:

/scalar

Do not treat that URL as available in the current branch until Scalar middleware/configuration has been added.

DocFX documentation

The project architecture calls for generated developer documentation using DocFX. No deployed DocFX URL is present in the checked-in repository metadata available for this README.

When the documentation site is deployed, place its public URL here, for example:

https://<documentation-host>/

The documentation should cover at minimum:

domain model;
application services;
repository contracts;
infrastructure adapters;
Web API controllers;
Telegram bot components;
public DTOs and configuration types.

Deployed application

No verified deployed application URL is currently recorded in the repository metadata used to prepare this README.

When deployment is available, publish the links here rather than using a placeholder:

Web application: <deployment-url>
API: <api-url>
Scalar: <api-url>/scalar
DocFX: <documentation-url>

This intentionally avoids inventing deployment addresses that are not present in the source repository.

Reproducing the project from scratch

A clean reproduction should follow this sequence:

Clone the repository.
Install .NET 10 SDK, Node.js and Docker.
Create local PostgreSQL environment variables from .example.env.
Start PostgreSQL with docker compose up -d postgres.
Restore the .NET solution.
Configure the Web API database connection and application secrets.
Apply EF Core migrations.
Seed development data if the current branch provides a seed implementation.
Install frontend dependencies with npm install.
Configure VITE_API_URL.
Start the Web API.
Start the Vite development server.
Verify the API/OpenAPI endpoint.
Verify authentication and protected routes once implemented.
Run unit and integration tests.
If using the Telegram bot, configure the bot token and start CinemaHikes.TelegramBotDownloader.
Install Playwright browser dependencies before exercising parser functionality.

Playwright

The Infrastructure project references Microsoft Playwright 1.62.0.

After restoring the project, install the browser required by the parser implementation according to the Playwright tooling available in the environment. Browser automation should be exercised separately from ordinary API development because it depends on external websites and their current markup and anti-bot behaviour.

Data model

The target database is PostgreSQL and is divided conceptually into several areas:

Identity
├── AspNetUsers
├── AspNetRoles
└── AspNetUserRoles

Catalog
├── Movies
├── Genres
├── MovieGenres
├── VideoSources
├── TranslationStudios
├── MovieLinks
└── Reviews

Users
├── FavoriteMovies
└── ViewHistory

Parsing
└── ParsingSourceConfigs

MovieLinks stores direct links together with video quality and translation-studio information. VideoSources stores source pages and their status/priority. This distinction allows the system to keep source metadata separate from the currently resolved direct media URL.

Security

The intended security model combines:

ASP.NET Core Identity for users and password hashing;
JWT for API authentication;
role-based protection for administrative operations;
EF Core parameterization for database access;
centralized exception handling;
HTTPS in deployed environments;
validation of incoming DTOs;
secrets kept outside source control.

Before production deployment, review the implementation against the current OWASP Top 10 and the applicable privacy and copyright requirements.

Performance and reliability targets

The SRS defines the following target characteristics:

API catalogue/search p95 below 300 ms under the specified test conditions;
player startup below 15 seconds to initial buffering;
Telegram search response below 1 second under normal conditions;
multiple source entries for important movies;
background revalidation of external links;
caching where required to reduce repeated parser work.

These are requirements targets, not measurements of the current repository branch.

Documentation map

Document Purpose

SRS.md Functional/non-functional requirements, use cases, risks and acceptance targets

README.md Developer-oriented setup and architecture overview

Architecture specification Detailed backend, frontend and database decomposition

OpenAPI Machine-readable HTTP API contract

DocFX Developer/reference documentation

Scalar Interactive API exploration

Project status

The repository currently combines a detailed SRS and architecture specification with an implementation that is still being built out. This README therefore documents both the intended system design and the verified state of the checked-in branch.

In particular, the current branch contains:

the .NET 10 solution structure;
Clean Architecture project boundaries;
the React/Vite frontend project;
PostgreSQL Docker Compose infrastructure;
EF Core / Identity / Playwright package references in Infrastructure;
detailed requirements and architecture documentation.

At the same time, the checked-in Web API bootstrap remains a minimal template. Full implementation of the SRS controllers, services, authentication, migrations, bot workflows, tests and documentation endpoints should be verified against the branch before claiming them as production-ready features.

Team

Hikers Team

The SRS identifies:

Andrey Volobuev (andrvol) --- Team Lead / Full Stack
Egor Tagirov (b1mq) --- Full Stack
Alexander Zagoruiko --- Project supervisor / instructor

License and academic context

The project is developed as a team academic project for an ASP.NET Core course. Licensing, redistribution of third-party content and operation of external media sources must be reviewed before public deployment.

sunmeat/README.md

Cinema Hikes

Project goals

Features

Catalogue

User account

Administration

Telegram bot

External video sources

Technology stack

Testing NUnit, with unit and integration-test projects planned in the solution

Architecture overview

Backend projects

Domain

Application

Infrastructure

Web API

Frontend

Repository structure

Prerequisites

Installation

Configuration

Environment variables

PostgreSQL

Frontend

Telegram

Database setup

Migrations

Seed data

Running the backend

Running the frontend

Running tests

Docker

API documentation

OpenAPI

Scalar

DocFX documentation

Deployed application

Reproducing the project from scratch

Playwright

Data model

Security

Performance and reliability targets

Documentation map

Scalar Interactive API exploration

Project status

Team

License and academic context

Reference materials