A Go REST API microservice that calculates flight paths from unordered flight segments. Given a list of [source, destination] pairs, it determines the complete path (starting airport to ending airport).

C4Context
    title System Context — flight-path
    Person(client, "API Client", "cURL, Postman, Newman, browser")
    System(flightpath, "flight-path", "Go REST API that reconstructs full itinerary from unordered flight segments")
    System_Ext(ghcr, "GitHub Container Registry", "Hosts multi-arch signed images")
    System_Ext(sigstore, "Sigstore", "Cosign keyless OIDC signing")
    Rel(client, flightpath, "POST /calculate", "HTTPS/JSON")
    Rel(flightpath, ghcr, "Published images", "docker push")
    Rel(flightpath, sigstore, "Signed by digest", "cosign OIDC")

    UpdateLayoutConfig($c4ShapeInRow="3")

See docs/ARCHITECTURE.md for Container, Component, request-flow sequence, and CI/CD pipeline diagrams.

make deps      # install dev tools (golangci-lint, gosec, swag, pnpm, newman, etc.)
make build     # generate Swagger docs + compile binary
make test      # run unit + handler tests
make run       # build and start the server
# Open http://localhost:8080/swagger/index.html

Install all required dev tools:

make deps

Layered Go microservice with a single HTTP endpoint over an in-memory algorithm — no database, no external services.

flowchart LR
    client["API Client<br/>(curl / Postman / browser)"]
    subgraph server["flight-path (Echo v5)"]
        mw["Middleware stack<br/>CORS · Secure · Recover<br/>Cache-Control · Gzip · BodyLimit 1 MiB"]
        routes["Routes<br/>POST /calculate<br/>GET /<br/>GET /swagger/*"]
        handlers["Handlers<br/>FlightCalculate<br/>ServerHealthCheck"]
        algo["FindItinerary()<br/>O(n) in-memory graph walk"]
    end
    client --> mw --> routes --> handlers --> algo

See docs/ARCHITECTURE.md for Container, Component, request-flow sequence, and CI/CD pipeline diagrams.

• POST /calculate — accepts [][]string flight segments, returns []string (start and end airports)
• GET / — health check
• GET /swagger/* — Swagger UI (http://localhost:8080/swagger/index.html)

Auto-generated OpenAPI spec: docs/swagger.json

Utilized Postman collection exported to JSON file and executes 18 test cases:

• HealthCheck — GET / returns {"data": "..."}
• UseCase01–03 — happy paths matching test-case-one, test-case-two, test-case-three (1, 2, 4 segments)
• UseCase04_EmptyBody — [] → 400 "empty segments"
• UseCase05_MalformedJSON — not valid json → 400 "parse"
• UseCase06_IncompleteSegment — [["SFO"]] → 400 "source and destination"
• UseCase07_ExtraItemsInSegmentIgnored — [["SFO","EWR","JFK"]] → 200, first two elements used
• UseCase08_TenSegmentChain — 10 scrambled segments resolving LAX→SFO, exercises the algorithm on longer inputs
• UseCase09_ObjectRoot — {"foo":"bar"} → 400 "parse" (wrong root JSON type)
• UseCase10_SecondSegmentIncomplete — [["SFO","EWR"],["JFK"]] → 400 with Index: 1 pointing at the offending segment
• HealthCheck_SecurityHeaders — asserts HSTS / X-Content-Type-Options / X-Frame-Options / CSP on /
• HealthCheck_CORS — asserts default Access-Control-Allow-Origin: *
• Swagger_UI — asserts GET /swagger/index.html returns 200 HTML
• UseCase11_WrongMethod — GET /calculate → 405
• UseCase12_UnknownRoute — GET /does-not-exist → 404
• UseCase13_LargeChain — 100-segment chain exercising the algorithm on wide inputs
• UseCase14_WrongContentType — text/plain body → 400 "content-type"

Uses hybrid validation: Ajv JSON Schema validation for /calculate response structure (global schemas defined at collection level) and Chai assertions for exact business values. The collection-level schema check skips non-/calculate requests so the HealthCheck assertions run in isolation.

Run make help to see all available targets.

GitHub Actions runs on every push to main, tags v*, and pull requests. All jobs live in a single workflow file (.github/workflows/ci.yml). Tag-gated jobs (goreleaser, docker) are siblings of the other jobs — they run only on v*.*.* pushes and are skipped on everything else.

Set secrets via Settings > Secrets and variables > Actions > New repository secret. Set variables via Settings > Secrets and variables > Actions > Variables tab > New repository variable.

Local-only variables (act): ACT=true is injected automatically by make ci-run (via --var ACT=true) to guard the dast job, which needs Docker-in-Docker for OWASP ZAP and doesn't run cleanly under act. Do not set ACT on GitHub Actions runners.

The docker job runs the following gates on every push. Gates 1–3 run unconditionally (catching Dockerfile and Trivy regressions on every commit). Gate 4 (multi-arch build) runs on every push but only pushes to GHCR on v*.*.* tag pushes. Gate 5 (cosign signing) is tag-only. Any failure blocks the release.

Inspect the published multi-arch manifest:

docker buildx imagetools inspect ghcr.io/andriykalashnykov/flight-path:<tag>

Expect linux/amd64 and linux/arm64 platform entries with no unknown/unknown rows.

Verify a published image's cosign signature:

cosign verify ghcr.io/andriykalashnykov/flight-path:<tag> \
  --certificate-identity-regexp 'https://github\.com/AndriyKalashnykov/flight-path/\.github/workflows/ci\.yml@refs/tags/v.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

A Claude Code workflow provides interactive mode (responds to @claude mentions from trusted authors) and automated PR review on every non-draft PR.

A Claude CI Fix workflow auto-triggers on CI failures for same-repo PR branches to attempt automated fixes with anti-recursion guards.

A cleanup workflow runs weekly (Sundays at 00:00 UTC) to delete old workflow runs (retain 7 days, keep minimum 5) and prune caches from merged/deleted branches.

Renovate keeps dependencies up to date with platform automerge enabled.

Contributions welcome — open an issue or pull request. Run make check locally before pushing.

MIT © Andriy Kalashnykov