# transparency-everywhere/ais-api architecture

> Architecture diagram of the GitHub repository transparency-everywhere/ais-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/transparency-everywhere/ais-api
- Repository: https://github.com/transparency-everywhere/ais-api

## Overview

AIS API is a discontinued vessel-position scraper/API. Clients request a vessel’s latest position, vessels in a port, an area, or near coordinates; the server dispatches to the corresponding scraper, maps results where applicable, and returns them. The combined position lookup compares MarineTraffic data with a VesselFinder fallback, which currently always reports an error. README documents discontinuation but no further product capabilities; scraper wiring is based on the sampled source.

Main entry points: [`api.js`](https://github.com/transparency-everywhere/ais-api/blob/main/api.js) (Position & Port API), [`server.js`](https://github.com/transparency-everywhere/ais-api/blob/main/server.js) (HTTP Server), [`area.js`](https://github.com/transparency-everywhere/ais-api/blob/main/area.js) (Area & Nearby Search), [`lib/puppeteer.js`](https://github.com/transparency-everywhere/ais-api/blob/main/lib/puppeteer.js) (Response Scraper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP API"]
  node_entry["App Entry<br/>[index.js]"]
  node_server["HTTP Server<br/>[server.js]"]
end

subgraph group_positions["Position Lookup"]
  node_api["Position &amp; Port API<br/>[api.js]"]
  node_vf["VesselFinder Stub<br/>[api.js]"]
  node_mt_position["MarineTraffic Position<br/>[api.js]"]
  node_combined["Latest Position<br/>[api.js]"]
end

subgraph group_vessels["Vessel Search"]
  node_port["Port Vessel Search<br/>[api.js]"]
  node_area["Area &amp; Nearby Search<br/>[area.js]"]
  node_area_query["Search Query Builder<br/>[area.js]"]
  node_result_map["Vessel Result Mapping<br/>[area.js]"]
end

subgraph group_scraping["Browser Scraping"]
  node_scraper["Response Scraper<br/>[puppeteer.js]"]
end

node_client(("API Client"))
node_marine["MarineTraffic"]

node_client -->|"HTTP requests"| node_server
node_entry -->|"starts"| node_server
node_server -->|"dispatches position and port"| node_api
node_server -->|"dispatches area and nearby"| node_area
node_api -->|"checks fallback"| node_vf
node_api -->|"checks position"| node_mt_position
node_api -->|"compares results"| node_combined
node_mt_position -->|"requests position data"| node_marine
node_api -->|"searches port"| node_port
node_port -->|"requests port data"| node_marine
node_area -->|"builds search"| node_area_query
node_area -->|"maps results"| node_result_map
node_area_query -->|"fetches response"| node_scraper
node_scraper -->|"loads reports"| node_marine
node_marine -->|"returns JSON"| node_scraper
node_server -->|"sends results"| node_client

click node_entry "https://github.com/transparency-everywhere/ais-api/blob/main/index.js"
click node_server "https://github.com/transparency-everywhere/ais-api/blob/main/server.js"
click node_api "https://github.com/transparency-everywhere/ais-api/blob/main/api.js"
click node_vf "https://github.com/transparency-everywhere/ais-api/blob/main/api.js"
click node_mt_position "https://github.com/transparency-everywhere/ais-api/blob/main/api.js"
click node_combined "https://github.com/transparency-everywhere/ais-api/blob/main/api.js"
click node_port "https://github.com/transparency-everywhere/ais-api/blob/main/api.js"
click node_area "https://github.com/transparency-everywhere/ais-api/blob/main/area.js"
click node_area_query "https://github.com/transparency-everywhere/ais-api/blob/main/area.js"
click node_result_map "https://github.com/transparency-everywhere/ais-api/blob/main/area.js"
click node_scraper "https://github.com/transparency-everywhere/ais-api/blob/main/lib/puppeteer.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_server,node_client toneBlue
class node_api,node_vf,node_mt_position,node_combined toneAmber
class node_port,node_area,node_area_query,node_result_map toneMint
class node_scraper toneRose
class node_marine toneIndigo
```

## Components

### HTTP API

- [App Entry](https://github.com/transparency-everywhere/ais-api/blob/main/index.js): `index.js`
- [HTTP Server](https://github.com/transparency-everywhere/ais-api/blob/main/server.js): `server.js`

### Position Lookup

- [Position & Port API](https://github.com/transparency-everywhere/ais-api/blob/main/api.js): `api.js`
- [VesselFinder Stub](https://github.com/transparency-everywhere/ais-api/blob/main/api.js): `api.js`
- [MarineTraffic Position](https://github.com/transparency-everywhere/ais-api/blob/main/api.js): `api.js`
- [Latest Position](https://github.com/transparency-everywhere/ais-api/blob/main/api.js): `api.js`

### Vessel Search

- [Port Vessel Search](https://github.com/transparency-everywhere/ais-api/blob/main/api.js): `api.js`
- [Area & Nearby Search](https://github.com/transparency-everywhere/ais-api/blob/main/area.js): `area.js`
- [Search Query Builder](https://github.com/transparency-everywhere/ais-api/blob/main/area.js): `area.js`
- [Vessel Result Mapping](https://github.com/transparency-everywhere/ais-api/blob/main/area.js): `area.js`

### Browser Scraping

- [Response Scraper](https://github.com/transparency-everywhere/ais-api/blob/main/lib/puppeteer.js): `lib/puppeteer.js`

### Other components

- **API Client**
- **MarineTraffic**

## Connections

- API Client → HTTP Server: HTTP requests
- App Entry → HTTP Server: starts
- HTTP Server → Position & Port API: dispatches position and port
- HTTP Server → Area & Nearby Search: dispatches area and nearby
- Position & Port API → VesselFinder Stub: checks fallback
- Position & Port API → MarineTraffic Position: checks position
- Position & Port API → Latest Position: compares results
- MarineTraffic Position → MarineTraffic: requests position data
- Position & Port API → Port Vessel Search: searches port
- Port Vessel Search → MarineTraffic: requests port data
- Area & Nearby Search → Search Query Builder: builds search
- Area & Nearby Search → Vessel Result Mapping: maps results
- Search Query Builder → Response Scraper: fetches response
- Response Scraper → MarineTraffic: loads reports
- MarineTraffic → Response Scraper: returns JSON
- HTTP Server → API Client: sends results