Info Hawker Australia Backend

Info Hawker Australia is a Deno-based backend that exposes fuzzy address search over the Australian G-NAF dataset while maintaining a separate application database.

Tech Stack

• Deno 2 runtime (TypeScript)
• Prisma ORM (Deno runtime target) with @prisma/adapter-pg
• PostgreSQL with pg_trgm and PostGIS extensions
• Pino logger
• pg connection pools via Prisma adapter
• Domain-driven design structure (application, domain, infrastructure, interfaces)

Project Structure

G-NAF/
├─ prisma/
│  ├─ schema.main.prisma        # Prisma schema for `info_hawker` DB
│  └─ schema.gnaf.prisma        # Prisma schema for `gnaf` DB
├─ scripts/
│  ├─ init-main-db.sql          # Enables pg_trgm in main DB
│  └─ init-gnaf-db.sql          # Enables postgis + pg_trgm in G-NAF DB
├─ src/
│  ├─ application/
│  │  └─ services/              # Use cases (e.g. address lookup)
│  ├─ config/                   # Environment loading and typed config
│  ├─ domain/
│  │  ├─ models/                # Entities & value objects
│  │  └─ repositories/          # Repository interfaces
│  ├─ infrastructure/
│  │  ├─ db/                    # Prisma clients, repositories, migrations
│  │  ├─ di/                    # Dependency injection container & bootstrap
│  │  └─ logging/               # Pino logger factory
│  └─ interfaces/
│     └─ http/                  # HTTP server, middleware, handlers
├─ deno.json                    # Tasks, import map aliases, formatting rules
└─ README.md                    # Project documentation

Environment Variables

Copy .env.example to .env and fill in values:

cp .env.example .env

Key variables:

• APP_PORT – HTTP server port
• MAIN_DATABASE_URL / MAIN_SHADOW_DATABASE_URL
• GNAF_DATABASE_URL / GNAF_SHADOW_DATABASE_URL
• LOG_LEVEL

Database Setup

1. Create two PostgreSQL databases: info_hawker (application) and gnaf (reference).
2. Run the initialization SQL scripts to enable required extensions:

psql -d info_hawker -f scripts/init-main-db.sql
psql -d gnaf -f scripts/init-gnaf-db.sql

3. Unpack the official G-NAF AUGUST 2025 dataset into data/raw/G-NAF AUGUST 2025/ (the existing data/Contents.txt lists every expected file).
4. Run deno task db:seed to load the reference data and bootstrap the application database.

Seeding

deno task db:seed performs two actions:

• Truncates every table in the gnaf schema and streams each .psv file through PostgreSQL's COPY ... FROM STDIN using pg-copy-streams. This preserves the split-per-state layout and requires a role that can toggle session_replication_role (superuser in the default docker setup).
• Refreshes the gnaf."ADDRESS_AUTOCOMPLETE" materialized view, keeping the autocomplete indexes in sync with the raw data.
• Inserts baseline tenants into the info_hawker database.

Seeding expects the raw dataset to remain in data/raw/G-NAF AUGUST 2025/Standard/ and data/raw/G-NAF AUGUST 2025/Authority Code/. The script logs per-table ingestion counts; enable LOG_LEVEL=debug for per-file progress when troubleshooting.

Docker Compose (optional)

A convenience docker-compose.yml is provided to bootstrap PostgreSQL 18 (Alpine) locally:

docker compose up -d

This starts postgres alongside pgAdmin and mounts the SQL initialization scripts. Update credentials in .env or the compose file as needed.

Prisma Workflow

Real Prisma clients are required to replace the placeholder stubs in src/infrastructure/db/generated/*/deno/edge.ts.

deno task prisma:generate

This runs both schemas sequentially:

deno task prisma:generate:main
deno task prisma:generate:gnaf

Ensure the MAIN_DATABASE_URL, MAIN_SHADOW_DATABASE_URL, GNAF_DATABASE_URL, and GNAF_SHADOW_DATABASE_URL variables are defined before running.

Running the Server

Development

deno task dev

Production

deno task start

API Endpoints

• GET /health — Health probe
• GET /addresses/search?q=<query>&limit=<n>&threshold=<float> — Fuzzy address suggestions using pg_trgm (alias: /addresses/autocomplete). Queries must be at least 2 characters and return id, displayLine (including level/flat/unit information), locality, state, postcode, and score for autocomplete drop-downs.
• GET /addresses/{addressDetailPid} — Returns the detailed G-NAF record (including coordinates and component parts) for a specific address
• GET /addresses/nearby?lat=<latitude>&lng=<longitude>&radius=<meters>&limit=<n> — Reverse lookup for the closest addresses to a latitude/longitude pair (defaults: radius=500m, limit=10)

Logging

Logging is handled by Pino. Configure LOG_LEVEL (info, debug, etc.) in the environment file.

Dependency Injection

Tokens are defined in @infrastructure/di/bootstrap.ts. Call setupContainer() before resolving dependencies (this is handled in src/main.ts).

Constraints & Rules

• Use Prisma with Deno runtime (runtime = "deno") and generated clients committed to src/infrastructure/db/generated/.
• Maintain separation between info_hawker (application) and gnaf (reference) databases.
• Keep new modules aligned with the existing DDD directory layout (application/, domain/, infrastructure/, interfaces/).
• SQL migrations should live in scripts/ or Prisma migrations as appropriate; enable pg_trgm for fuzzy search.
• Avoid circular dependencies in DI registrations.
• Update documentation when adding new tasks or environment variables.

Development Notes

• Run deno fmt and deno lint per repo defaults.
• When adding new HTTP handlers, register them through the DI container and createHttpServer() routing.
• Placeholder Prisma clients will throw if used before generation—always run deno task prisma:generate after schema changes.

License

Internal project. Add licensing details here if the project becomes public.