# Development Setup

## Prerequisites

- Elixir 1.17+
- Erlang/OTP 26+
- PostgreSQL 16+ with PostGIS extension
- Node.js 20+ (for asset compilation)

## Quick Start

```bash
# Clone and cd
git clone <repo-url>
cd aprs.me

# Install dependencies and set up database
mix setup

# Start dev server
mix phx.server
# or with IEx:
iex -S mix phx.server
```

The application will be available at `http://localhost:4000`.

## Nix Development Environment (Optional)

A reproducible development environment is available via Nix:

```bash
nix develop
# or with direnv:
direnv allow
```

This provides all required tooling (Elixir, Erlang, PostgreSQL, Node.js) without manual installation.

## Database Setup

The `mix setup` command:
1. Installs Hex and Rebar dependencies
2. Fetches Elixir dependencies
3. Creates the development database
4. Runs migrations
5. Seeds device data

### Manual Database Setup

```bash
mix ecto.create
mix ecto.migrate
mix run priv/repo/seeds.exs
```

**Important:** PostGIS extension must be enabled on the database. The migration pipeline handles this, but ensure your PostgreSQL installation includes PostGIS.

## Running Tests

```bash
# Full test suite
mix test

# Watch mode (auto-rerun on changes)
mix test.watch

# Coverage report
mix coveralls.html
# View at cover/excoveralls.html
```

## Code Quality

```bash
# Format code
mix format

# Static analysis
mix credo --strict

# Type checking
mix dialyzer

# Security scan
mix sobelow
```

## Asset Compilation

Frontend assets use ESBuild + Tailwind CSS v4:

```bash
# Development (watch mode)
mix assets.build

# Production
MIX_ENV=prod mix assets.deploy
```

JavaScript entry points are in `assets/js/`:
- `app.ts` — Core application (always loaded)
- `map.ts` — Map functionality (lazy-loaded)
- `map_helpers.ts` — Leaflet utilities
- `map_fixes.ts` — Leaflet bug workarounds

CSS: Tailwind v4 in `assets/css/app.css` with custom dark mode and Leaflet overrides.

## Useful Commands

| Command | Purpose |
|---|---|
| `mix phx.server` | Start dev server |
| `iex -S mix phx.server` | Start with interactive shell |
| `mix test` | Run test suite |
| `mix test.watch` | Auto-rerun tests on changes |
| `mix format` | Format Elixir code |
| `mix credo --strict` | Lint check |
| `mix dialyzer` | Type checking |
| `mix sobelow` | Security scan |
| `mix coveralls.html` | Test coverage report |
| `mix phx.routes` | List all routes |
| `mix ecto.migrate` | Run pending migrations |
| `mix ecto.rollback` | Rollback last migration |
| `mix parse_file <path>` | Parse raw APRS log file |

## Project Structure

See [AGENTS.md](../../AGENTS.md) for coding conventions, and [Architecture Overview](../architecture/overview.md) for system design.