Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.appliedaifoundation.org/llms.txt

Use this file to discover all available pages before exploring further.

Business logic does not live in API routes. API routes are thin wrappers. Logic lives in src/lib/services/.

​
The five services

​
FleetService.ts

The big one. Aggregates fleet-wide metrics for the home page, EU ETS dashboard, and FuelEU dashboard. Methods include:
  • getFleetSummary(year, ytd?) — KPIs for the home page
  • getFleetVessels(year) — per-vessel metrics for the fleet table
  • getFleetEmissionsDaily(year) — daily timeline for the home page chart
  • getEUETSCost(year) — fleet-wide ETS cost projection
  • getFuelEUCompliance(year) — fleet-wide GHG intensity, balance, penalty
Has a 30-second request-level cache for the expensive EU metrics queries.

​
VoyageSegmentService.ts

Voyage segmentation used by every page that touches voyages. Methods:
  • getVesselVoyageSegments(imo, year) — list of segments with EU metrics, fuel breakdown, CII per segment
  • getFleetVoyages(year) — flat list of all segments across fleet for ETS dashboard
Wraps extractVoyageLegs() from portClassifier.ts and adds caching and aggregation.

​
VesselService.ts

Per-vessel reads:
  • getVesselDetails(imo) — header info
  • getVesselAnnualSummary(imo, year) — vessel detail page data
  • getVesselCIIDaily(imo, year) — rolling CII chart data
  • getVesselPositions(imo, year) — Maps page positions

​
UploadService.ts

Two flows:
  • previewUpload(buffer, vesselId) — parse, validate, count duplicates, return preview
  • commitUpload(buffer, vesselId) — same parse + actual insert

​
ReportExportService.ts

PDF generation for the five regulatory reports. Each method takes the same inputs the dashboard already has access to:
  • generateIMODCS(imo, year)
  • generateCIIStatement(imo, year)
  • generateEUMRV(imo, year)
  • generateEUETSReport(year) (fleet-level)
  • generateFuelEUReport(year) (fleet-level)

​
Why services, not API-route logic

  • Reuse. VoyageSegmentService is called from 4 different API routes. Putting logic in routes would mean copy-paste.
  • Testability. Services are pure-ish; routes are coupled to Request/Response.
  • Same code path everywhere. Reports use the same service the dashboard uses. No “report-time” recalculation drift.

​
Caching strategy

FleetService has a 30-second in-process cache keyed on year + ytd. Multiple parallel requests during a single dashboard load (summary + vessels + emissions-daily) all hit the same cached intermediate computations.

​
Calculator utilities

The services delegate the actual maths to pure utility files:
  • src/lib/utils/ciiCalculator.ts
  • src/lib/utils/fuelEUCalculator.ts
  • src/lib/utils/portClassifier.ts
These are zero-dependency TypeScript modules — they’re imported by services, by API routes, and by the methodology page’s interactive calculators.