• 

• 

• 

• 

• 

• 

• 

Tavall Couriers and Logistics

Inspiration

I wanted to start a medical courier business, but there we're no out-of-the-box logistics solutions for people taking on delivery from pickup (intake) to the last mile.

What it does

Tavall Couriers and Logistics is a full courier workflow platform that moves a shipment from intake to final delivery with a single, consistent system. It starts at intake: a merchant can scan a printed label or intake page, extract shipping metadata, create a label record, and queue it for downstream processing. Drivers can scan the same QR label to update delivery status, and customers can track shipments with their tracking number in a public, read-only view.

The platform is built around a "dumb label / smart scanner" approach. The QR code itself only stores a UUID. The intelligence lives behind authenticated services that resolve that UUID, enforce permissions, and apply business rules. That keeps physical labels safe while the system stays flexible as rules evolve.

Key workflows include:

• Merchant intake scanning and label creation.
• Driver state transitions (pickup, in transit, delivered) with guardrails.
• Route planning that orders stops and produces a Google Maps route link.
• Customer tracking pages that show label details and delivery status.

Visual flow references:

How we built it

The platform is three modules working together:

• gemini-api handles AI client abstractions and response parsing.
• internal-courier-api handles the core domain logic, routing, caching, and shared services.
• spring-webview renders the UI with Spring Boot + Thymeleaf and lightweight JavaScript.

Core stack

The stack is intentionally lean: Java 25 with preview features, Spring Boot 4.0.2, Postgres, Thymeleaf, and hand-tuned CSS/JS. This keeps the UI fast and removes npm supply chain risk without sacrificing capability.

AI and scanning pipeline

Gemini 3 Flash powers OCR + QR extraction. Gemini 3 Pro is used for routing and Google Maps-based route link generation. The system uses function-calling schemas for deterministic outputs and a strict parsing layer to sanitize responses.

We also use LiveAPI for a first-pass address visibility check during intake scans only. The system then validates and persists labels asynchronously so the scanner can keep moving without blocking the operator.

Routing and logistics

Routes are built from newly intaked labels and existing route constraints. Gemini 3 Pro uses Google Maps grounding to estimate travel times, then orders stops and produces a route link that is stored in delivery_routes.route_link.

Caching and storage

The platform uses a custom in-memory cache with a bucket architecture (1 key to many values) for fast reads and rich metadata. Postgres is the durable system of record and is used to rehydrate caches.

Frontend and UX

The UI is server-rendered with Thymeleaf and uses a shared popup/modal system for scanning and label details. The layout is mobile-friendly and the UI state is kept consistent with server-rendered values and small JS event handlers.

Security model

Security is built around role-based access, a dumb label design, and the assumption that clients and networks are hostile. QR codes store only UUIDs, and the system gates all actions behind authenticated roles.

Challenges we ran into

1. Scan concurrency and UI latency. OCR + QR extraction can take multiple seconds. We moved scanning into async tasks and optimized the UI to show progress while background work completes.
2. Wasted compute on bad frames. We built a local "bouncer" to reject dark or low-contrast frames before calling Gemini.
3. Thread scalability. Standard thread pools were too heavy for scan-heavy workloads. We migrated to Java 25 virtual threads for per-scan isolation.
4. Agentic latency. The tool-calling loop was too slow; we use deterministic schemas that force function-style responses in a single round-trip.
5. Cost control. We introduced tiered model escalation (Flash Lite -> Flash/Pro) and token-saving strategies to keep routing costs predictable.
6. Frontend complexity. We avoided a heavy JS framework and kept the UI server-rendered to reduce risk and maintain performance.

Reference visuals:

Accomplishments that we're proud of

• Built a full intake-to-delivery workflow with a single UUID label system.
• Achieved deterministic AI outputs with schema-based function calling.
• Created a custom, typed caching layer with metadata-rich keys.
• Designed a low-latency scan UX with async processing and LiveAPI gating.
• Implemented route building with Google Maps grounding and generated route links.
• Delivered a no-build frontend that is fast, secure, and easy to maintain.

What we learned

• Deterministic outputs beat open-ended prompts for mission-critical logistics.
• Virtual threads unlock massive concurrency for scan-heavy workloads without complex thread pools.
• Guarding AI calls with local checks and tiered validation saves real money.
• Keeping the QR label "dumb" simplifies security and allows server rules to evolve.
• Server-rendered UI plus minimal JS is still a powerful pattern for operational tools.

What's next for Tavall Couriers and Logistics

• Expand routing intelligence for new intaked packages with configurable radius and max-stop limits.
• Improve the routing selection logic to balance deadlines, distance, and route capacity.
• Add more structured delivery state analytics for operations dashboards.
• Continue hardening the scanning pipeline for noisy, low-quality camera inputs.
• Fix the Maven POM structure and unify build pipelines across modules.

Built With

• ai
• css
• gemini
• html
• java
• javascript
• pdfbox
• postgresql
• spring
• spring-boot
• thymeleaf
• zxing