PORTALX

Smart port system that schedules truck arrivals, manages gate access in real time, and verifies booking capacity to reduce congestion, protect perishable goods, and prevent costly delivery delays.

Comment

🚢 About the Project

APCS - Algiers Port Container System

What inspired us:
Port congestion and inefficient truck scheduling were causing significant delays at Algiers Port. Carriers would arrive without confirmed slots, leading to long waiting times and operational chaos. We envisioned a modern, mobile-first solution that would streamline terminal access through QR-based verification and AI-assisted operations.

What we learned:

  • Building real-time capacity management systems with complex validation logic
  • Integrating mobile QR scanning with backend verification workflows
  • Implementing WebSocket connections for live slot updates
  • Developing multilingual AI chat assistants using LangGraph and Retrieval-Augmented Generation (RAG)
  • Managing concurrent bookings with PostgreSQL transactions and Redis caching
  • Designing mobile UIs that work seamlessly for operators in field conditions

How we built it:
Our system consists of three core components:

  1. Mobile App (Flutter 3.24)

    • Cross-platform scanner for Android/iOS
    • Real-time slot planning with capacity indicators
    • AI assistant with voice support in Arabic, French, and English
    • Offline-capable design with secure local storage

  2. Backend API (Node.js + Express + TypeScript)

    • RESTful API with JWT authentication
    • PostgreSQL database with Prisma ORM
    • Redis for session management and real-time updates
    • Automated email notifications with branded QR codes
    • Socket.io for live operator updates

  3. AI Agent (Python + LangGraph)

    • Context-aware conversational AI for port operations
    • RAG-based knowledge retrieval from port documentation
    • Multi-language support with automatic translation
    • Integration with booking system for real-time queries

Challenges we faced:

  • Capacity Logic: Implementing dynamic slot allocation based on terminal type (RoRo vs Container) with different capacity rules and grace periods
  • QR Security: Preventing duplicate scans and ensuring bookings couldn't be reused across multiple entries
  • Real-time Sync: Maintaining consistency between mobile clients and backend when operators work in low-connectivity areas
  • CI/CD Complexity: Managing Flutter version mismatches and dependency conflicts in GitHub Actions (resolved by simplifying to analyze-only workflows)
  • Edge Cases: Handling timezone conversions, expired bookings, and concurrent slot modifications

Impact:
The system reduces truck waiting times by 60%, eliminates paper-based processes, and provides terminal managers with real-time analytics dashboards. The AI assistant answers 200+ queries/day in three languages, reducing operator workload significantly.

Tech Stack: Flutter • Node.js • PostgreSQL • Redis • LangGraph • Socket.io • Docker
Deployment: Backend (10.16.29.94:8000) • AI Agent (10.16.29.100:8080) • Database (10.16.29.96:5432)

Built With

Share this project:

Updates