# Trackling

Trackling is a web-based virtual companion hidden inside an original schematic Metro map. Astro and React provide the browser interface; Rust and Axum provide the same-origin backend that will eventually integrate WMATA transit data.

## Current Status

Milestone 1 is in progress. The foundation currently includes:

- Astro 7 with React 19
- A responsive original schematic placeholder
- A typed health API client
- A fixture-backed `/api/v1/world` endpoint
- An Axum server with `/api/v1/health`
- Static Astro serving from Axum in production
- Fixture/live/unconfigured server modes
- Nix development environment
- Multi-stage container definition

See [slop.md](slop.md) for the product plan and [astro-rust-plan.md](astro-rust-plan.md) for the implementation plan.

## Prerequisites

Use Nix for the pinned development tools:

```sh
nix develop
```

Node dependencies are installed with npm:

```sh
npm --prefix web install
```

## Development

Run Astro and Axum together:

```sh
nix develop -c make dev
```

The frontend dev server is at `http://localhost:4321`. The Rust server is at `http://localhost:8080`.

To run each process separately:

```sh
npm --prefix web run dev
nix develop -c cargo run --manifest-path server/Cargo.toml
```

## Checks

```sh
nix develop -c make check
nix develop -c make test
nix develop -c make build
```

## Configuration

Copy `.env.example` to `.env` for local configuration. The WMATA key must only be provided to the Rust process. It must never be prefixed with `PUBLIC_` or placed in frontend source.

- `BIND_ADDR`: Rust listen address, default `0.0.0.0:8080`.
- `STATIC_DIR`: built Astro directory, default `../web/dist` from `server`.
- `WMATA_FIXTURE_DIR`: optional existing directory containing `world.json` for fixture mode.
- `WMATA_API_KEY`: reserved for the future live WMATA adapter.
- `RUST_LOG`: Rust log filter, default `info`.

## Production

Build Astro and Axum locally:

```sh
nix develop -c make build
STATIC_DIR="$PWD/web/dist" nix develop -c cargo run --manifest-path server/Cargo.toml --release
```

Build the single container:

```sh
docker build -t trackling .
docker run --rm -p 8080:8080 trackling
```

The container serves both the Astro site and Rust API on port `8080`.

## WMATA Attribution

The planned transit integration will use data provided by WMATA. Transit information may be delayed, incomplete, or inaccurate. Trackling is an independent application and is not affiliated with or endorsed by WMATA. The project will use original map artwork and will follow the [WMATA Transit Data Terms of Use](https://developer.wmata.com/license).