Nautilus

For developers

If you're a developer evaluating Nautilus as a contributor, an integrator's engineer, or a tenant's in-house engineering team — this page is for you.

You can read the full spec at docs/requirements-and-features.md, the architecture at the Architecture page, and the Tier-C interface specs at docs/integrations/. This page is the developer-experience entry point.

What kind of project Nautilus is

  • AGPL-3.0 — full source, full transparency.
  • Microservices, event-first. 16 domain services on NATS JetStream with Quanta's agent contract.
  • Polyglot but disciplined. Go for backend services, TypeScript + React / React Native for frontends, Python for AI workloads (Heimdall + model-bearing tiers of Quanta agents). Divergence from the defaults is allowed but must be deliberate.
  • GitOps end-to-end. ArgoCD + GitHub Actions, Helm charts per domain.
  • Public roadmap. Public issue tracker. Public ADRs.

Repository structure

The exact mono-repo vs poly-repo layout is being finalized; the developer docs at docs/adr/ capture the decision. Either way, the conceptual layout is:

nautilus/
├── domains/
│   ├── 01-identity/
│   ├── 02-reservation/
│   ├── 03-billing/
│   ├── 04-pos/
│   ├── 05-gangway/
│   ├── 06-muster/
│   ├── 07-dining/
│   ├── 08-excursions/
│   ├── 09-spa/
│   ├── 10-crew/
│   ├── 11-materials/
│   ├── 12-fleet/
│   ├── 13-quanta-services/
│   ├── 14-comms/
│   ├── 15-frontends/
│   └── 16-telehealth/
├── frontends/
│   ├── pwa/                   # POS / kiosk / iTV / signage
│   └── mobile/                # React Native (iOS / Android)
├── platform/
│   ├── helm/                  # Helm charts per domain
│   ├── argocd/                # GitOps app definitions
│   ├── kong/                  # decK declarative gateway config
│   ├── cilium/                # CNI + policy
│   └── cnpg/                  # CloudNativePG operator config
├── docs/
│   ├── requirements-and-features.md
│   ├── adr/                   # architectural decision records
│   ├── integrations/          # Tier-C interface specs
│   └── ...
├── CONTRIBUTING.md
├── SECURITY.md
├── CODE_OF_CONDUCT.md
├── CLA.md
└── LICENSE                    # AGPL-3.0

Local development

The full stack runs locally on docker-compose for development.

  • docker-compose up boots the local stack: NATS JetStream, Postgres-per-domain (lightweight), Zitadel, Kong, mock CRS (Versonix Seaware reference shape), mock Heimdall (no GPU required), mock ConnectOne for SIP/voice work, and Redis.
  • Reference seeds per domain populate enough state to drive an end-to-end smoke test.
  • make smoke runs the smoke test across the local stack.

The mocks for Heimdall and ConnectOne are deliberate — they let you do most domain development without provisioning GPU or PBX infrastructure.

Local development guide →

Architectural decision records

ADRs capture decisions and trade-offs publicly. Recent / canonical ADRs:

  • ADR-001 — Choose NATS JetStream + Quanta agent contract for the bus.
  • ADR-002 — Postgres + CloudNativePG as the per-service database; no MongoDB / Couchbase in the AGPL tree.
  • ADR-003 — Kong Gateway OSS as the API gateway shore and onboard.
  • ADR-004 — Cilium covers CNI, encryption, policy, and observability; no service mesh in Phase 1–3.
  • ADR-005 — React PWA + React Native for frontends; one codebase, multiple form factors; no native iTV stack.
  • ADR-006 — ConnectOne is the comms platform; SPMS domains never embed their own SIP/WebRTC.
  • ADR-007 — Heimdall is the content-safety + analysis service; no closed CSAM-detection black box.
  • ADR-008 — Tier-C interfaces are CC BY 4.0 specs + Apache 2.0 conformance harnesses.
  • ADR-009 — Dual-license (AGPL-3.0 + commercial); CLA via Apache ICLA + CCLA pattern.

ADRs live in docs/adr/.

Issue triage process

The public issue tracker is the conversation surface for bugs, features, and design discussions.

  • Labels: bug, feature, discussion, good first issue, help wanted, domain:NN, tier:A|B|C, phase:N.
  • Triage cadence: weekly. Issues labeled within 7 days; out-of-scope or stale issues closed with reasoning.
  • Discussion-first for design changes. Open a discussion issue before opening a PR for a non-trivial design change. Reduces review thrash.
  • good first issue is curated. Pick one if you're new.

Contribution flow

  1. Read CONTRIBUTING.md.
  2. Sign the CLA (Apache ICLA + CCLA pattern).
  3. Pick an issue (good first issue if you're new) or open a discussion for a new feature.
  4. Fork and branch.
  5. Run the local stack (docker-compose up, make smoke).
  6. Write tests — unit per service, integration where the change crosses the bus.
  7. Open a PR referencing the issue.
  8. Review. A maintainer from the relevant domain reviews; cross-domain changes get two reviewers.
  9. Merge. Squash by default; rebase-merge for series of related commits.

Code conventions

  • Commit messages: Conventional Commits (feat:, fix:, chore:, docs:, refactor:, test:).
  • Lint and test pass before review. CI enforces.
  • No trailing TODOs in merged code. Open an issue and reference it instead.
  • No "AI-generated code" without review. Same standard as any other PR.
  • Comments explain why, not what. Identifiers carry the what.

Where we particularly want help

  • CRS adapter authors. Versonix Seaware is the first-class reference; Infor Cruise and others are wide open.
  • GRMS hardware integrators. KNX / BACnet / DALI / vendor adapters per vessel class.
  • Regulatory-reporting specialists. Jurisdictions beyond the initial set.
  • Per-tenant launch partners. Phase-1 / Phase-2 reference vessels.
  • Tier-C spec authors. Heimdall API, CallCraft agent contract, ConnectOne signaling, Quanta keys-service, iTV/GRMS adapter, fleet federation.
  • Performance engineering. 5,000+ pax tuning is a Phase 6 problem coming up fast.
  • Frontend accessibility. WCAG 2.1 AA across PWA + mobile + signage.

Security disclosure

Security issues go to security@nautilus.dev (or the address listed in SECURITY.md). Do not open a public issue for a security disclosure.

We aim to acknowledge within 48 hours, triage within 7 days, and coordinate disclosure on a timeline appropriate to the severity. Tier-A primitives (the bus + agent contract, Signal-Protocol library, PSI module) get expedited handling because of the audit commitment.

CONTRIBUTING → SECURITY → CODE_OF_CONDUCT → CLA → Browse the repo → Browse good-first-issues → ADRs →