Cargo Planning System (Prolab Project)

This project is a web-based station–vehicle–route planning system for cargo collected from districts of Kocaeli and delivered to Kocaeli University.

The application consists of two main parts:

• Backend: REST API implemented with FastAPI (backend/)
• Frontend: Web UI built with plain HTML/CSS/JavaScript (frontend/)

---

📋 Features

• Station Management: List and manage cargo stations
• Vehicle Management: Manage vehicles, capacities and basic properties
• Route & Trip Management: Manage routes and trips between stations
• Cargo Status Tracking: View cargo status per station on the user side
• Admin Panel: Screens for stations, routes, vehicles and reports
• User Panel: View cargo status and trips after logging in

---

🏗️ Technology Stack

• Backend

  • FastAPI (Python)
  • SQLAlchemy (ORM)
  • PostgreSQL database
  • Alembic / SQL migration files (backend/migrations/)

• Frontend

  • Plain HTML, CSS, JavaScript
  • Simple multi-page structure (not SPA)

---

🚀 Setup

1. Requirements

• Python 3.10+
• PostgreSQL (local installation recommended)
• Optional: pgAdmin or any DB management tool

---

2. Backend Setup (backend/)

cd backend

# Create virtual environment (recommended)
python -m venv venv
venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt

# Create .env from example
copy env.example .env   # In PowerShell you can also use: cp env.example .env

Configure the database connection in .env:

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/cargo_plan
DEBUG=True

Then create a PostgreSQL database named cargo_plan.

Load initial data

cd backend
python scripts/seed_stations.py
python scripts/seed_vehicles.py

Run the backend

cd backend
uvicorn app.main:app --reload

The API will be available at http://localhost:8000 by default.

---

3. Frontend Setup (frontend/)

This folder does not use Node/Vite/React; files are served as static HTML/CSS/JS.
To avoid CORS and browser security issues, do not open HTML files via file://, use an HTTP server instead.

Option 1: Python HTTP server (simple)

cd frontend
python -m http.server 8001

Then open in your browser: http://localhost:8001 (you will be redirected to the login page).

Option 2: Node.js http-server

npm install -g http-server
cd frontend
http-server -p 8001

Backend API base URL

The backend URL is defined in frontend/js/api.js via the API_BASE_URL constant. Default:

const API_BASE_URL = "http://localhost:8000/api";

Change this value if your backend is running on a different host/port.

---

📖 Usage Flow

1. Start the backend

   cd backend
   uvicorn app.main:app --reload

2. Serve the frontend with an HTTP server (e.g. python -m http.server 8001 in frontend/)
3. Open http://localhost:8001 in your browser
4. Create a new user if needed (register.html)
5. Log in as admin or regular user and use the corresponding panels

---

📁 Project Structure (Overview)

Prolab-Project-cargo-plan/
├── backend/
│   ├── app/
│   │   ├── api/        # API endpoints
│   │   ├── models/     # SQLAlchemy models
│   │   ├── schemas/    # Pydantic schemas
│   │   ├── services/   # Business logic / service layer
│   │   └── utils/      # Helper utilities
│   ├── scripts/        # Seed and helper scripts
│   ├── migrations/     # SQL migration files
│   └── README.md       # Backend-specific notes
│
├── frontend/
│   ├── css/            # Stylesheets
│   ├── js/             # Frontend JavaScript
│   ├── admin/          # Admin HTML pages
│   ├── user/           # User HTML pages
│   └── README.md       # Frontend-specific notes
│
├── data/
│   └── stations.json   # Station data
└── README.md           # This file

---

🧪 Tests

There are ready-to-run backend test scripts:

cd backend

# General API tests
python test_api.py

# Scenario tests
python test_scenarios.py

# Route finding test
python test_route_finding.py

---

📄 Note

This project is a sample university course (Prolab) cargo planning system.