Fast Express KDS

Fast Express KDS is a decision support workspace built for middle managers in cargo operations. It combines branch analytics, personnel scoring, cross-branch comparison, reporting, and an inflation-aware forecasting service in one browser-based flow.

The opening visual above is assembled from the original report screens so the repository presents the real project surfaces instead of a generic banner.

What the system covers

• Branch-level performance analysis with yearly cargo, income, cost, rent, and profit views
• Personnel analytics with scored performance, delivery ratios, and "employee of the month" summaries
• Cross-branch comparison across selectable periods
• Forecasting service that uses historical branch data and inflation trend projection
• Reporting views for branch-oriented operational review
• Session-based login flow for the main dashboard routes

Product surfaces

• public/login.html: login screen for authenticated access
• public/index.html: operational home dashboard with top-line metrics and charts
• public/subeler.html and public/sube_analiz.html: branch selection and branch drill-down
• public/personel.html: personnel scoring, ranking, and comparison
• public/karsilastirma.html: map-backed cross-branch comparison flow
• public/tahminleme.html: branch selection plus forecast generation
• public/raporlama.html: report selection and branch summaries

Architecture

• app.js runs the main Express application, session management, MySQL queries, dashboard APIs, and protected routes.
• app.py exposes the forecasting endpoint and computes branch projections with linear regression and an inflation adjustment.
• public/ contains the interface layer for login, dashboards, charts, branch analysis, personnel review, comparison, forecasting, and reporting.
• MySQL is the operational data source for branches, personnel, cargo history, and cost calculations.
• data-seeder.js is preserved as a database validation helper for an already imported course schema.

Academic context

• Course: YBS 3015 Karar Destek Sistemleri
• Project title: Fast Express Kargo KDS
• Project window: Oct 2024 - Dec 2024
• Student: Batuhan Yüksel

The original project goal was to support middle-management decisions such as branch performance review, profitability tracking, and branch opening or closure evaluation through data-backed views instead of manual interpretation.

Tech stack

Area	Tools
Web app	Node.js, Express.js, Express Session
Forecasting service	Python, Flask, scikit-learn, NumPy
Database	MySQL, mysql2
Frontend	HTML, CSS, JavaScript, Chart.js, Leaflet
Operations	node-cron, bcrypt, dotenv

Repository structure

.
|-- app.js
|-- app.py
|-- data-seeder.js
|-- package.json
|-- public/
|   |-- index.html
|   |-- subeler.html
|   |-- sube_analiz.html
|   |-- personel.html
|   |-- karsilastirma.html
|   |-- tahminleme.html
|   |-- raporlama.html
|   `-- login.html
`-- docs/assets/

Running locally

1. Install the Node.js dependencies:

   npm install

2. Create an environment file from the provided example:

   cp .env.example .env

3. Install the Python forecasting service dependencies:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt

4. Make sure the MySQL schema from the original course delivery is already imported into the fast_express database.

   The public repository includes the application code and a database validation helper, but it does not reconstruct the full schema from scratch.

5. Optionally verify that the imported database contains the expected core tables:

   npm run db:check

6. Start the Express app:

   npm start

7. Start the forecasting API in a second terminal:

   source .venv/bin/activate
   python app.py

8. If your database still stores plain-text legacy passwords, enable one-time password migration before the first boot:

   AUTO_HASH_LEGACY_PASSWORDS=true npm start

The public interface labels are primarily Turkish because the project was originally delivered for a local academic setting.

Notes on scope

• This repository is strongest as an academic product case study and dashboard implementation.
• The forecasting flow is intentionally lightweight and centered on the course deliverable rather than production-grade model operations.
• The codebase contains both the operational dashboard and the small Python forecasting sidecar because that split is part of the original project structure.

License

Released under the MIT License.