Artifacts

Required deliverables beyond application code.

Configuration

Kubernetes Manifests

Location: k8s/

File	Purpose
namespace.yaml	Namespace definitions (galaxy-dev, galaxy-prod)
secrets.yaml	Secret templates (JWT key, DB credentials, admin password)
configmap.yaml	Non-sensitive configuration (tick_rate, start_date)
postgres.yaml	PostgreSQL deployment, service, PVC
redis.yaml	Redis deployment, service, PVC
{service}.yaml	Deployment and service for each game service
ingress.yaml	Ingress rules for external access

Dockerfiles

Location: services/{service}/Dockerfile

Each service has a Dockerfile following best practices:

• Multi-stage builds where beneficial
• Non-root user
• Minimal base image
• Health check defined

Game Configuration

Location: config/

File	Purpose
celestial-bodies.yaml	Body properties (mass, radius, color)
ship-defaults.yaml	Default ship specifications
server.yaml	Server configuration defaults
ephemeris-j2000.json	Bundled fallback ephemeris data for J2000 epoch

Schemas

OpenAPI Specifications (External REST API)

Location: specs/api/

File	Purpose
api-gateway.yaml	REST endpoints (auth, services)
websocket.yaml	WebSocket message schemas
admin.yaml	Admin API endpoints

Protocol Buffers (Internal gRPC)

Location: specs/api/

File	Purpose
physics.proto	Physics service gRPC interface
players.proto	Players service gRPC interface
galaxy.proto	Galaxy service gRPC interface
tick-engine.proto	Tick engine gRPC interface
common.proto	Shared message types (vec3, quaternion, etc.)

JSON Schemas

Location: specs/data/

File	Purpose
ship.schema.json	Ship state structure
player.schema.json	Player account structure
celestial-body.schema.json	Body state structure
game-state.schema.json	Full game state for snapshots

Database

Location: db/

File	Purpose
migrations/	PostgreSQL migration scripts
schema.sql	Full schema for reference

Tests

Behavior Specifications

Location: specs/behavior/

Directory	Purpose
physics/	Physics validation scenarios
players/	Authentication, registration scenarios
ships/	Ship control, services scenarios
admin/	Admin action scenarios

Format: Gherkin .feature files

Unit Tests

Location: services/{service}/tests/

• pytest for Python services
• Jest for web client
• Minimum coverage: see testing.md

Integration Tests

Location: tests/integration/

• End-to-end scenarios
• API contract tests
• WebSocket communication tests

CI/CD

Container Registry

Images are published to GitHub Container Registry (GHCR):

• Registry: ghcr.io/erikevenson/galaxy-<service>
• Tags per image:
  • Semver: 1.122.2 (read from pyproject.toml or package.json)
  • Git SHA: abc1234 (first 7 characters)
  • latest
• Authentication: GITHUB_TOKEN (automatic in GitHub Actions)

Local development continues to use unqualified image names (galaxy-<service>) with imagePullPolicy: IfNotPresent — no GHCR dependency for local builds.

GitHub Actions

Location: .github/workflows/

File	Purpose
docs.yml	Build and deploy documentation (exists)
build-push.yml	Build all service images, push to GHCR on merge to main (exists)
ci.yml	Run tests on PR
deploy-dev.yml	Deploy to galaxy-dev namespace
deploy-prod.yml	Deploy to galaxy-prod namespace

build-push.yml — Image Build & Push

• Trigger: Push to main branch
• Strategy: Matrix build — one job per service, all run in parallel
• Services built (9 total):
  • Python with proto: api-gateway, physics, tick-engine, players, galaxy
  • Node.js: web-client, admin-dashboard
  • Python without proto: admin-cli
  • Database: db-migrations
• Build context preparation: Python services that need proto files have specs/api/proto/*.proto copied into their build context before building. The galaxy service also gets config/ephemeris-j2000.json.
• Permissions: packages: write (push to GHCR), contents: read (checkout)

Scripts

Location: scripts/

File	Purpose
setup-dev.sh	Set up local development environment
run-tests.sh	Run full test suite
build-images.sh	Build all container images
fetch-ephemeris.py	Fetch initial ephemeris data from JPL

Documentation

Project Root

File	Purpose
README.md	Project overview, quick start
CONTRIBUTING.md	How to contribute
LICENSE	Apache License 2.0

Service READMEs

Location: services/{service}/README.md

Each service README includes:

• Purpose and responsibilities
• Configuration options
• API endpoints (if applicable)
• Local development instructions
• Testing instructions

Guides

Location: docs/guides/

File	Purpose
deployment.md	How to deploy to Kubernetes
development.md	Local development setup
troubleshooting.md	Common issues and solutions

Directory Structure

galaxy/
├── .github/
│   └── workflows/
├── config/
│   ├── celestial-bodies.yaml
│   ├── ship-defaults.yaml
│   └── server.yaml
├── db/
│   ├── migrations/
│   └── schema.sql
├── docs/
│   └── guides/
├── k8s/
│   ├── namespace.yaml
│   ├── secrets.yaml
│   ├── configmap.yaml
│   ├── postgres.yaml
│   ├── redis.yaml
│   ├── ingress.yaml
│   └── {service}.yaml
├── scripts/
├── services/
│   ├── tick-engine/
│   ├── physics/
│   ├── players/
│   ├── galaxy/
│   ├── api-gateway/
│   ├── web-client/
│   ├── admin-cli/
│   └── admin-dashboard/
├── specs/
│   ├── api/
│   ├── architecture/
│   ├── behavior/
│   ├── data/
│   └── mechanics/
├── tests/
│   └── integration/
├── CLAUDE.md
├── CONTRIBUTING.md
├── LICENSE
└── README.md