Laboratory Shop

Laboratory Shop is a production‑ready, scalable Telegram‑based ecommerce bot for vape products. Built with FastAPI, PostgreSQL, Redis, and Docker, it was actively used by real customers before being closed by the founder. This page dives into the architecture, key modules, and code snippets that demonstrate how the system works under the hood.

1. Features
2. Architecture & Tech Stack
3. Database Schema
4. Core Modules
   • Main Shop Handlers
   • Order Flow & Cart Management
   • Admin Dashboard
5. Deployment
6. Future Improvements

• User Shopping Flow
  • Browse products by category
  • Add/remove items in cart
  • Checkout with address or postal office selection
• Session Management
  • Persistent carts in Redis for each user
  • Rate‑limiting and session expiry
• Admin Dashboard
  • Approve/reject orders
  • Inventory management
  • View sales & customer analytics
• Notifications
  • Order status updates via Telegram
  • Low‑stock alerts
• Security
  • Telegram OAuth for user identity
  • Role‑based access for admins

• Aiogram: handles Telegram message & callback queries

• PostgreSQL + SQLAlchemy + Alembic: relational database & migrations

• Redis: in‑memory cart/session storage, rate‑limiting

• Docker & Docker Compose: containerization and service orchestration

• AWS EC2: Linux-based VPS

• Cloudinary: Photo-storing

• GitHub Actions: CI/CD for building & pushing Docker images (in progress)

Link to code snippet

• Main Shop Handlers

  • This module contains all the Telegram bot command and callback handlers powered by Aiogram. It routes user messages, presents product catalogs, processes “Add to Cart” actions and navigates users through the shop flow. Handlers are organized by feature (e.g. shop_handlers, cart_handlers, checkout_handlers) and each exposes clear entry points:

  • Link to code snippet for shop_handlers

  Video Demonstration

• Order Flow & Cart Management

  • This service layer handles all cart operations and checkout logic, using Redis for fast, in‑memory session storage. Key responsibilities include storing per‑user carts, enforcing TTL expiration, calculating totals, and orchestrating the creation of Order and OrderItem records in PostgreSQL via SQLAlchemy:

  • Link to code snippet for cart_handlers
  • Link to code snippet for cart_redis

  Video Demonstration

• Admin Dashboard

  • All administrative functions are handled directly through the Telegram bot, allowing managers to:
    1. Manage Inventory
       • Add new products or update existing item details (price, stock, description)
       • Record incoming supplies and adjust stock levels on the fly
    2. Process Orders
       • View incoming order requests with full details (user info, delivery method, cart contents)
       • Approve or reject orders, with automatic status updates sent to customers
       • Track order history and filter by status, date, or manager
    3. Issue Promo Codes
       • Generate and revoke promotional codes from within the bot interface
       • Set code parameters (discount value, expiry date, usage limits)
  • Link to code snippet for admin/order
  • Link to code snippet for admin/supply

  Video Demonstration (from manager's account)

Services are defined in docker-compose.yml:

services:
  redis:
    image: redis:latest
    container_name: redis
    command: redis-server --save 60 1 --loglevel warning
    restart: on-failure
    ports:
      - "6379:6379"
    networks:
      - bot_network

  db:
    image: postgres:16-alpine
    container_name: db
    restart: on-failure
    env_file:
      - .env
    volumes:
      - pgdata:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    networks:
      - bot_network
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 5

  bot:
    build: .
    container_name: bot
    command: sh -c "make migrate && python -m main"
    env_file:
      - .env
    volumes:
      - ./migrations:/migrations
    restart: always
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    networks:
      - bot_network

volumes:
  pgdata:

networks:
  bot_network:
    driver: bridge

To deploy on your Linux server:

1. Clone repo
2. Set environment variables
3. docker-compose up -d –build

• Migrate Admin from Telegram → Django web admin
• Integrate payment processing (Stripe, crypto)
• Add user reviews & ratings in bot
• Horizontal scaling with Kubernetes