ACT-Rental - Cinema Equipment Rental Management System

Description

ACT-Rental is a comprehensive system for managing cinema equipment rentals. It allows managers to control equipment availability, handle bookings, and track equipment returns efficiently.

Documentation

• Project Architecture - Detailed system architecture and design decisions
• Development Plan - Current development status and roadmap
• Code Style Guide - Coding standards and best practices
• Project Structure - Detailed explanation of project organization
• Technical Requirements - Project specifications and requirements
• Changelog - History of notable changes and improvements

Features

• Equipment management with hierarchical categories and tree view
• Client management with fast search functionality
• Booking system with quantity support and availability checking
• Barcode scanner integration (HID scanner + scan sessions with server sync)
• Real-time equipment status updates with rental status badges
• Document generation (rental agreements, handover acts)
• Project management with card/table views, URL state persistence, and payment tracking
• React frontend with TypeScript, URL-shareable filter state, and vitest testing
• Local static asset management for reliable operation
• macOS desktop launcher for Docker stack management

Tech Stack

• Backend: FastAPI + Python 3.12
• Frontend (Legacy): Jinja2 + Bootstrap + Vanilla JS
• Frontend (New): React 18 + TypeScript + Vite + shadcn/ui + TanStack Query
• Database: PostgreSQL
• Cache: Redis
• Containerization: Docker
• Testing: pytest (backend), Vitest + Testing Library (frontend)

Project Structure

act-rental/
├── backend/              # Backend application
│   ├── api/             # API endpoints and routers
│   │   └── v1/         # API version 1
│   ├── core/           # Core functionality and config
│   ├── models/         # Database models
│   ├── schemas/        # Pydantic schemas
│   ├── services/       # Business logic layer
│   └── repositories/   # Database access layer
├── docs/               # Project documentation
│   ├── architecture.md       # System architecture
│   ├── code_style.md        # Coding standards
│   ├── development_plan.md  # Development roadmap
│   ├── project_structure.md # Project organization
│   └── specs/               # Technical specifications
├── frontend/           # Legacy frontend (Jinja2 + Bootstrap)
│   ├── static/        # Static assets (CSS, JS, images)
│   └── templates/     # Jinja2 HTML templates
├── frontend-react/     # New React frontend (migration in progress)
│   ├── src/
│   │   ├── components/  # Shared UI components (shadcn/ui)
│   │   ├── features/    # Feature modules (clients, equipment, projects, bookings, scanner, categories)
│   │   ├── hooks/       # Custom React hooks (useUrlState, useDebounce, etc.)
│   │   ├── services/    # API service layer
│   │   └── types/       # TypeScript type definitions
│   ├── vitest.config.ts # Test configuration
│   └── package.json
├── ACT-Rental-Launcher/ # macOS desktop launcher (PyQt5)
├── tests/              # Backend test suite
│   ├── unit/          # Unit tests
│   ├── integration/   # Integration tests
│   ├── e2e/           # End-to-end tests
│   └── factories/     # Test data factories
├── docker/            # Docker configuration files
├── migrations/        # Alembic migration scripts
├── scripts/           # Utility scripts (backups, maintenance)
├── pyproject.toml     # Project metadata and dependencies
└── requirements.txt   # Python dependencies

Prerequisites

• Docker and Docker Compose
• Python 3.12
• PostgreSQL 14+
• Redis 6+

Environment Variables

Database Settings

• POSTGRES_USER - PostgreSQL username (default: postgres)
• POSTGRES_PASSWORD - PostgreSQL password (default: postgres)
• POSTGRES_DB - Database name (default: act-rental)
• POSTGRES_SERVER - Database host (default: db)

Redis Settings

• REDIS_HOST - Redis host (default: redis)
• REDIS_PASSWORD - Redis password (optional)

Application Settings

• SECRET_KEY - Secret key for JWT tokens and security
• DEBUG - Enable debug mode (default: false)
• WORKERS_COUNT - Number of uvicorn workers (default: 1)
• LOG_LEVEL - Logging level (default: info)

Security Settings

• ALLOWED_HOSTS - Comma-separated list of allowed hosts
• CORS_ORIGINS - Comma-separated list of allowed CORS origins

Development setup

1. Clone the repository
2. Copy .env.example to .env and adjust values
3. Run development server:

docker compose up

React Frontend Development

cd frontend-react
npm install
npm run dev      # Start Vite dev server on port 5173
npm run build    # Production build (tsc + vite build)
npm run test     # Run vitest test suite
npm run lint     # Run ESLint

Testing

Backend Testing

To run the entire test suite, including unit, integration, and E2E tests with coverage reporting, use the following Make command:

make test

This command utilizes the docker-compose.test.yml configuration. It performs the following steps:

1. Builds the necessary Docker images using Dockerfile.test.
2. Starts the required services (test database and Redis) in the background.
3. Runs pytest within a dedicated container, executing all tests found in the tests/ directory.
4. Collects code coverage for the backend directory.
5. Displays a coverage report with missing lines in the terminal.
6. Generates an HTML coverage report (usually in the htmlcov/ directory).

To run specific tests or pass additional options to pytest, you can execute the docker compose run command directly:

# Example: Run only tests in a specific file
docker compose -f docker-compose.test.yml run --rm test python -m pytest tests/integration/test_bookings.py

# Example: Run tests matching a keyword expression (-k)
docker compose -f docker-compose.test.yml run --rm test python -m pytest -k "test_create_booking"

Frontend Testing

cd frontend-react
npm run test          # Single run (CI)
npm run test:watch    # Watch mode (development)

Test suite includes 25 tests covering useUrlState hook, PaginationControls, and StatusGroup components.

CI/CD with GitHub Actions

This project uses GitHub Actions for continuous integration:

Automated Workflows

1. Run Tests - Runs all tests in Docker containers when code is pushed to main or develop branches

   • Builds test containers
   • Runs tests with PostgreSQL and Redis in containers
   • Generates and uploads test coverage reports as GitHub artifacts

2. Code Quality - Checks code quality when code is pushed to main or develop branches

   • Runs Black for code formatting
   • Runs isort for import sorting
   • Runs flake8 for code style
   • Runs mypy for type checking

3. Build Docker Image - Builds and tests Docker image

   • Builds Docker image with optimized layers
   • Verifies the image works correctly
   • Creates and uploads instructions for local deployment

Local Development

For local development, you can use Docker Compose:

# Start all services in development mode with auto-reload
docker compose up

# Run in detached mode
docker compose up -d

Production

1. Copy .env.example to .env.production and set secure values
2. Build and run production services:

docker compose -f docker-compose.prod.yml up -d

Dependencies Installation

This project uses uv for fast dependency management. The dependencies are defined in pyproject.toml. You can install them using the provided Make commands or manually with uv.

For Development

# Create virtual environment and install dependencies
make install

# Or manually
python -m venv .venv
source .venv/bin/activate  # for Linux/macOS
# or
.venv\Scripts\activate  # for Windows

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install development dependencies (including core dependencies)
uv pip install -e ".[dev]"

For Testing

# Install testing dependencies
make install-test

# Or manually with uv
uv pip install -e ".[test]"

Development

• Follow Code Style Guide
• Use pre-commit hooks
• Write tests for new features
• Update documentation

Migrations

To apply migrations and update the database schema:

# Apply all migrations
alembic upgrade head

# Create a new migration
alembic revision -m "your_migration_name"

# Roll back the last migration
alembic downgrade -1

# Check migration history
alembic history

Future Migrations

The migrations/versions/future directory contains migrations that are prepared but not yet applied:

To apply a future migration:

# Move the migration to the main versions directory
mv migrations/versions/future/your_migration_name.py migrations/versions/

# Apply the migration
alembic upgrade head