# Filmvisarna AB – Project Summary

## Project overview

**Filmvisarna AB** is a full-stack cinema booking platform built for browsing films, viewing showtimes, selecting seats and tickets, completing bookings, managing accounts, and administering cinema data.

The project demonstrates practical experience with frontend development, backend API design, relational databases, authentication, real-time updates, third-party API integration, email delivery, automated testing, and team-based GitHub development.

- **Repository:** [filmvisarna-ab](https://github.com/alireza8850/filmvisarna-ab)
- **Project type:** Full-stack web application
- **Architecture:** Client–server architecture with a React frontend, .NET backend, and MySQL database

## Main functionality

### Customer features

- Browse currently available films and showtimes
- Search and filter films
- View film details, posters, trailers, actors, genres, descriptions, and age limits
- Select a cinema hall, seats, and ticket types
- Create cinema bookings
- Receive booking confirmation by email
- Cancel bookings according to the cancellation rules
- Register, log in, log out, and view booking history
- Use the AI cinema assistant
- Submit contact messages

### Staff and administrator features

- Manage films, showings, halls, seats, ticket types, ticket prices, bookings, and users
- Search up bookings for administration purposes
- Manage access-control rules
- Separate permissions for visitors, users, staff, and administrators

## Technology stack and purpose

| Area | Technology/tool | Purpose |
|---|---|---|
| Frontend | React 19 | Build reusable, interactive user-interface components |
| Frontend language | TypeScript | Add static typing and safer frontend development |
| Build tool | Vite | Fast local development server and production builds |
| Routing | React Router DOM | Page navigation and route-based application structure |
| UI framework | Bootstrap and React-Bootstrap | Responsive layout and reusable UI elements |
| Styling | Sass/SCSS | Structured, maintainable custom styling |
| Icons | Bootstrap Icons and React Icons | User-interface icons |
| Backend | .NET 10 Minimal API | Implement HTTP endpoints, business logic, authentication, and server-side functionality |
| Backend data handling | DynData | Dynamic C# objects, arrays, JSON handling, and logging utilities |
| Database | MySQL | Store users, sessions, films, halls, seats, showings, tickets, prices, bookings, actors, and contact messages |
| Database driver | MySqlConnector | Connect the .NET backend to MySQL and execute parameterized queries |
| Authentication | Session cookies | Maintain logged-in user sessions using `session_id` cookies |
| Authorization | Custom ACL system | Restrict routes and operations based on visitor, user, staff, and admin roles |
| Password security | BCrypt.Net-Next | Hash and verify user passwords |
| Email | MailKit and MimeKit | Send booking confirmations and other transactional emails through SMTP |
| AI integration | HTTP client + Nodehill AI proxy | Forward chat requests to an AI service with a project-specific system prompt |
| Film data integration | The Movie Database (TMDB) API | Retrieve upcoming movies, movie details, trailers, credits, and release information |
| Real-time communication | Server-Sent Events (SSE) | Push seat-booking and seat-release updates to users in real time |
| Unit/component testing | Vitest, Testing Library, jsdom | Test frontend components and API-related behavior |
| End-to-end testing | Playwright | Test complete browser workflows in Chromium |
| Code quality | ESLint | Identify JavaScript/TypeScript code-quality issues |
| Source control | Git and GitHub | Collaborate, review code, and manage project history |

## Architecture

```text
Browser
  └─ React + TypeScript + Vite
       ├─ REST requests with fetch()
       ├─ Session cookies
       └─ Server-Sent Events for live seat updates
            │
            ▼
.NET 10 Minimal API backend
  ├─ Authentication and sessions
  ├─ ACL authorization
  ├─ Booking and seat validation
  ├─ AI chat proxy
  ├─ Email service
  └─ REST API endpoints
            │
            ▼
MySQL database
  ├─ Users and sessions
  ├─ Films and actors
  ├─ Halls and seats
  ├─ Showings and ticket prices
  └─ Bookings and tickets
```

## API capabilities

The API is documented in [API-CONTRACT.md](API-CONTRACT.md).

### Authentication

- `POST /api/register` – Register a user
- `POST /api/login` – Log in and create a session
- `GET /api/login` – Check the current session
- `DELETE /api/login` – Log out

### Film discovery

- `GET /api/films` – List and filter films
- `GET /api/films/{id}` – Get film details
- `GET /api/films/{filmId}/showings` – Get showtimes for a film

### Booking

- `POST /api/bookings` – Create a booking
- `POST /api/bookings/cancel` – Cancel a booking
- `GET /api/bookings/my` – Get the logged-in user’s bookings
- `GET /api/seats-sse/{showingId}` – Receive live seat availability events

### Additional services

- `POST /api/chat` – Send messages to the AI assistant
- `POST /api/contact` – Submit a contact message
- Generic CRUD routes for supported database tables, including halls, seats, ticket types, prices, actors, and showings

## API keys and sensitive configuration

**No secret values should be included in project documentation or committed to GitHub.** The repository uses configuration placeholders and the following integrations require credentials in a local `backend/db-config.json` file:

| Configuration | Required for | Storage key | Notes |
|---|---|---|---|
| MySQL credentials | Database connection | `host`, `port`, `username`, `password`, `database` | Required to start the backend and initialize/seed the database |
| AI access token | AI assistant | `aiAccessToken` | Sent as a Bearer token to the AI proxy; keep private |
| SMTP credentials | Booking confirmation emails | `smtpServer`, `smtpPort`, `emailUsername`, `emailPassword` | Used by MailKit to authenticate with the email provider; keep private |
| TMDB API key | Upcoming movie and movie-detail requests | Currently defined in `src/utils/tmdbService.ts` | This key is exposed in frontend code and should be moved to backend/environment configuration before production |

### Security note

The repository currently contains a TMDB key in frontend source and seeded development account data in backend code. For a production-ready version, rotate any exposed credentials, remove real-looking seeded credentials, use environment variables or a secret manager, and avoid committing secrets to source control.

## Local setup

1. Clone the repository:

   ```bash
   git clone https://github.com/alireza8850/filmvisarna-ab.git
   cd filmvisarna-ab
   ```

2. Create the local database configuration:

   ```bash
   cp backend/db-config.template.json backend/db-config.json
   ```

3. Fill in the local MySQL, AI, and SMTP values in `backend/db-config.json`.

4. Install frontend dependencies and start the development environment:

   ```bash
   npm install
   npm run dev
   ```

5. The documented development URLs are:

   - Frontend: `http://localhost:5173`
   - Backend/API: `http://localhost:3000`

## Testing and quality checks

Available commands from `package.json`:

```bash
npm run build       # TypeScript check and Vite production build
npm run lint        # ESLint checks
npm run test:run    # Run Vitest tests once
npm run test:ui     # Run frontend/UI tests
npm run test:api    # Run API tests
npm run test:e2e    # Run Playwright browser tests
```

The test suite covers:

- Authentication and registration API flows
- Film API behavior
- Frontend page and component behavior
- Booking workflows through the browser

## Engineering highlights

- Implemented a complete cinema booking flow from film discovery through seat selection and confirmation.
- Added backend validation to prevent double booking and return conflict responses.
- Used session-based authentication with role-based access control.
- Added real-time seat updates with Server-Sent Events.
- Integrated external movie data through TMDB.
- Added an AI assistant behind a backend proxy so the browser does not directly call the AI provider.
- Added SMTP email delivery for booking confirmations.
- Documented API contracts, architecture, technical debt, and planned improvements.
- Added automated API, UI, and end-to-end test layers.

## Known improvement areas

The project documentation identifies realistic future improvements:

- Add global backend exception middleware and more consistent status-code handling.
- Add rate limiting and brute-force protection for login.
- Move exposed third-party keys into secure backend configuration.
- Improve seat locking with time-limited reservations.
- Split large frontend components into smaller focused components.
- Add a global React error boundary and consistent loading states.
- Add an administrator statistics dashboard.
- Add password reset by email.
- Add a CI/CD pipeline.

## Collaboration

- Worked in an **Agile team environment** with iterative development, shared responsibilities, API documentation, testing, and continuous improvement.

## One-paragraph project summary

Filmvisarna AB is a full-stack cinema booking system developed with React, TypeScript, Vite, Bootstrap, Sass, .NET 10 Minimal API, and MySQL. The application supports film discovery, showtimes, seat selection, ticket booking, cancellation, user authentication, role-based administration, booking emails, AI chat, TMDB movie-data integration, and real-time seat updates through Server-Sent Events. The project also includes API documentation and automated testing with Vitest, Testing Library, and Playwright, demonstrating practical experience in building, integrating, testing, and documenting a complete web application.