# Pharos Platform

A service-first starting point based on the multilingual DDD reference, with
infrastructure conventions adapted from Pharos Platform's `architecture-reset`
branch. Metallo now contains internal Execution Core Run/Attempt identity and
persistence; user-facing business workflows remain future work.

The platform skeleton is on `main`. The previous platform tree is preserved
under `legacy/` with `git mv`.
The archive is excluded from active builds and workspaces; verification checks
all archived blobs and file modes against [docs/legacy-manifest.json](docs/legacy-manifest.json).

| Service | Language | Role |
| --- | --- | --- |
| `services/web` | Next.js / TypeScript | Static presentation, local sessions and Protobuf Centrifugo client |
| `services/api` | Go | Session authority, HTTP routing and realtime authorisation |
| `services/metallo` | Python | Independent domain-service composition and delivery foundations |
| `services/themelio` | Python | Empty Dependency Injector composition and typed transaction/delivery foundations |
| `services/beto` | Go | Independent domain-service composition and delivery foundations |

Every domain service owns its `services`, `contexts`, `foundation`, `contracts`,
`integrations` and transport/persistence folders. Metallo has an explicit
`adaptors` folder; Go technical adaptors live under its service-local foundation.
Metallo owns `execution_core` and Beto owns `support`; Themelio's context folder remains empty.
There is no root business-context implementation and no cross-service source import.

## Develop against your dev box

[Download Pharos DX for macOS, Windows or Linux](https://github.com/pharos-ai-factory/pharos-platform/releases)
and follow the [installation guide](dx/common/desktop/README.md#install-pharos-dx).
GitHub repository access is required.

Start with the **[developer guide](docs/development.md)**: prepare your VM, save
your `.env`, set up the platform, then edit and reload services locally.
It covers Pharos DX and Make commands side by side, including Colima on macOS,
delivering a commit and resetting a dev box. Detailed deployment reference is in
the [dev-box setup guide](dx/common/GUIDE.md).

## Start locally with Minikube

Prerequisites: Docker, Minikube, kubectl, Node.js 24, pnpm 10.34.5, Python 3.13+
and uv 0.12.19. Verification needs Go 1.27.1, or the pinned Docker fallback.

```sh
pnpm install --frozen-lockfile
pnpm dev:configure
pnpm dev:up
pnpm dev:forward
```

Open **https://platform.localtest.me** through the dev-box edge, or
**http://127.0.0.1:28000** for the Minikube forward, and sign in using
`OPERATOR_PASSWORD` from the private, ignored `.local/dev.env`. This fixed development operator is a technical
session scaffold. Production identity and business authorisation remain future work.

`dev:up` creates the dedicated `pharos-fresh` Minikube profile with containerd
and Calico, builds and loads the six application images, provisions separate
Kubernetes Secrets, and applies the local Kustomize overlay. The stack includes
PostgreSQL, RabbitMQ, persistent session Valkey, disposable realtime-history
Valkey, Centrifugo and the restricted realtime gateway. An administrator bootstrap
creates Execution Core's private database, applies its baseline schema and supplies
Metallo only its restricted runtime URL and Execution Core Project publisher key.
Other context delivery remains idle until it declares typed messages.

Local Minikube has no AAI installation. Its Site API serves Runtime routes with
Kubernetes TokenReview; member offline-consent routes stay disabled until an AAI
client is configured. The dev-box deployment supplies that configuration.

Only the web edge is forwarded to localhost. Internal diagnostics, administration
and connect/refresh proxy endpoints remain outside browser ingress.

```sh
pnpm dev:status
pnpm dev:logs -- --service metallo
pnpm dev:render
pnpm dev:down               # Stop the profile; preserve its PVCs and data
```

`PHAROS_MINIKUBE_PROFILE` selects a separate profile. `.local/dev.env` supports
protected `<KEY>_FILE` references instead of inline developer credentials.
Generated credentials are delivered only to their owning workload.

## Verify

```sh
pnpm verify
pnpm test:integration
pnpm test:browser           # Against the running Minikube stack
pnpm generate:contracts
pnpm check:large-file-review
```

The real infrastructure lane creates an isolated, ephemeral Docker project from
the same rendered Kubernetes workload definitions. Its technical fixture exists
only in tests; it does not populate the service context folders. It tests database
atomicity, receipts, optimistic concurrency, lease fencing, restricted broker
credentials, confirmed retry delivery, all application images and independent
browser sessions. Docker is a test harness; Minikube is the local deployment path.

See [TESTING.md](TESTING.md) for evidence limits and
[docs/verification.md](docs/verification.md) for the recorded checks, and
[devops/README.md](devops/README.md) for the k3s development-host bootstrap.
GitHub Actions uses the `architecture-reset` ARM64 runner pool and pinned actions.
Optional development-image publication runs only after the full CI gate and
publishes signed, immutable image digests; it does not activate a cluster.

## Architecture decisions

The [ADR catalogue](docs/decisions/README.md) includes the historical records and
current platform decisions, with numbering and provenance notes.

## Add a context

Follow [docs/adding-a-context.md](docs/adding-a-context.md). Decide the owner and
aggregate boundary first, then register its schema, typed event/projection
contracts, ports, adaptors and composition. The empty registries deny unknown
events, publishers and subscriptions. Adding a context requires explicit routing
and credentials rather than inferred authority from a folder name.

The foundations use current-state persistence with durable event delivery.
Event-sourced aggregate reconstruction is a separate future decision.

Read [ARCHITECTURE.md](ARCHITECTURE.md), [DDD.md](DDD.md),
[CLIENT-SUBSCRIPTIONS.md](CLIENT-SUBSCRIPTIONS.md), [CONTRIBUTING.md](CONTRIBUTING.md)
and [AGENTS.md](AGENTS.md) before changing these boundaries.

## Sources and licences

Runtime foundations derive from the sibling
`ddd-hexagonal-cqrs-es-eda-microservices-multilingual` project. CI pins and the
k3s development-host pattern derive from `architecture-reset` at `b228782dd`.
See [docs/decisions/0034-fresh-skeleton.md](docs/decisions/0034-fresh-skeleton.md)
and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). The reference's MIT notice
is retained in `LICENSE`; the reused development-host material retains its Apache
notice in `devops/LICENSE`.