95 lines
4.3 KiB
Markdown
95 lines
4.3 KiB
Markdown
|
# go-caatsm (Civil Aviation Authority Telegram Message Processor)
|
||
|
|
|
||
|
|
## Project Overview
|
||
|
|
|
||
|
|
`go-caatsm` is a high-performance Go application designed to process aviation telegrams (like FPL, ARR, DEP) and weather reports (METAR, SPECI, TAF) from NATS JetStream, parse them, persist them to PostgreSQL/TimescaleDB, and republish the parsed results. It follows Clean Architecture principles to ensure modularity and testability.
|
||
|
|
|
||
|
|
## Architecture
|
||
|
|
|
||
|
|
The project is structured using Clean Architecture:
|
||
|
|
|
||
|
|
* **`cmd/`**: Application entry points. `cmd/main` is the primary service, `cmd/seed-telegrams` is a utility for generating test data.
|
||
|
|
* **`internal/domain/`**: Core business logic and types (e.g., `aviation.go`, `fpl.go`, `weather/`). Pure Go, no dependencies on outer layers.
|
||
|
|
* **`internal/app/`**: Application business rules (use cases). `MessageProcessor` orchestrates the flow between ports.
|
||
|
|
* **`internal/adapter/`**: Adapters for external interfaces.
|
||
|
|
* `parser/`: Logic to parse raw telegram text into domain objects.
|
||
|
|
* `aviation/`: Aviation telegram parser (ARR, DEP, CNL, DLA, FPL)
|
||
|
|
* `weather/`: Weather report parser (METAR, SPECI, TAF)
|
||
|
|
* `composite.go`: Composite parser that routes messages to appropriate parser
|
||
|
|
* `validator/`: AFTN protocol validation.
|
||
|
|
* `dto/`: Data Transfer Objects.
|
||
|
|
* **`internal/infra/`**: Infrastructure implementations.
|
||
|
|
* `nats/`: NATS JetStream consumer and publisher.
|
||
|
|
* `postgres/`: Database repository using `pgx`.
|
||
|
|
* `config/`, `log/`, `telemetry/`, `monitoring/`: Cross-cutting concerns.
|
||
|
|
* **`internal/port/`**: Interfaces defining the contracts for repositories, publishers, and parsers.
|
||
|
|
* **`pkg/di/`**: Dependency Injection using Google Wire.
|
||
|
|
|
||
|
|
## Tech Stack
|
||
|
|
|
||
|
|
* **Language:** Go 1.24+
|
||
|
|
* **Messaging:** NATS JetStream
|
||
|
|
* **Database:** PostgreSQL (with TimescaleDB extension for time-series data)
|
||
|
|
* **Observability:** OpenTelemetry (OTLP), Prometheus, Jaeger, Grafana, Zap Logger
|
||
|
|
* **CLI:** `urfave/cli`
|
||
|
|
* **DI:** Google Wire
|
||
|
|
* **Testing:** Ginkgo (BDD), Gomega, Testcontainers (integration tests)
|
||
|
|
|
||
|
|
## Key Commands (Taskfile)
|
||
|
|
|
||
|
|
The project uses `Taskfile.yml` for managing common tasks.
|
||
|
|
|
||
|
|
* **Build:** `task build` (Output: `bin/receiver`)
|
||
|
|
* **Run (Dev):** `task run-dev` (Connects to local Docker stack)
|
||
|
|
* **Run (Prod):** `task run-prod`
|
||
|
|
* **Test (Unit):** `task test`
|
||
|
|
* **Test (Integration):** `task test-int` (Requires Docker)
|
||
|
|
* **Lint:** `task lint`
|
||
|
|
* **Start Infrastructure:** `task up` (Starts Postgres, NATS, Observability stack)
|
||
|
|
* **Stop Infrastructure:** `task down`
|
||
|
|
* **Seed Data:** `task seed` (Injects sample telegrams into NATS)
|
||
|
|
|
||
|
|
## Configuration
|
||
|
|
|
||
|
|
Configuration is managed via TOML files in `configs/` and environment variables.
|
||
|
|
* `configs/config.dev.toml`: Default for development (`GO_ENV=dev`).
|
||
|
|
* `configs/config.prod.toml`: Production settings (`GO_ENV=prod`).
|
||
|
|
* Environment Variables: Prefix `CAATSM_` (e.g., `CAATSM_NATS_URL`, `CAATSM_POSTGRES_URL`).
|
||
|
|
|
||
|
|
## Development Workflow
|
||
|
|
|
||
|
|
1. **Start Infrastructure:**
|
||
|
|
```bash
|
||
|
|
task up
|
||
|
|
```
|
||
|
|
2. **Run Service Locally:**
|
||
|
|
```bash
|
||
|
|
task run-dev
|
||
|
|
```
|
||
|
|
3. **Generate Traffic:**
|
||
|
|
```bash
|
||
|
|
task seed
|
||
|
|
# OR for continuous traffic
|
||
|
|
task seed-slow
|
||
|
|
```
|
||
|
|
4. **Observe:**
|
||
|
|
* Grafana: http://localhost:3000 (admin/admin)
|
||
|
|
* Jaeger: http://localhost:16686
|
||
|
|
* Prometheus: http://localhost:9090
|
||
|
|
|
||
|
|
## Key Files & Directories
|
||
|
|
|
||
|
|
* `cmd/main/main.go`: Application entry point. Sets up config, DI, and starts the listener.
|
||
|
|
* `internal/app/processor.go`: `MessageProcessor` - The core orchestration logic.
|
||
|
|
* `internal/adapter/parser/`: Contains parsers for aviation telegrams and weather reports (composite pattern).
|
||
|
|
* `internal/infra/nats/consumer.go`: JetStream consumer implementation.
|
||
|
|
* `internal/infra/postgres/telegrams.ddl`: Database schema.
|
||
|
|
* `docs/`: Extensive documentation (Architecture, NATS, Dev Guide).
|
||
|
|
|
||
|
|
## Notes for AI Agent
|
||
|
|
|
||
|
|
* **Conventions:** Follow existing patterns in `internal/`. Use `internal/port` for interfaces.
|
||
|
|
* **Testing:** New features must include Ginkgo tests. Integration tests should be added for infrastructure components.
|
||
|
|
* **DI:** If adding new components, update `pkg/di/wire.go` and run `task wire` (or `task generate`).
|
||
|
|
* **Safety:** Always check `go.mod` before adding imports.
|