Phase 0 scaffold: arcadia-cloud Phoenix service

API-only Phoenix 1.8 project for cloud-ops, inventory, billing, and
provisioning sagas. Validates arcadia JWTs via shared Guardian secret
(verify-only; arcadia-app remains the issuer).

Deps beyond default Phoenix: guardian, cors_plug, oban, req.
Postgres on local port 5433 per arcadia stack convention.
Endpoint runs on :4005.

Endpoints:
- GET /api/health         — public, returns service identifier
- GET /api/v1/inventory   — auth-gated, returns empty list (phase 0 stub)

Oban configured with the queues phase 1+ will need:
provisioning / cloud_sync_fast|full|slow / cloud_billing / metering.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

lib/arcadia_cloud.ex

@@ -0,0 +1,9 @@
+defmodule ArcadiaCloud do
+  @moduledoc """
+  ArcadiaCloud keeps the contexts that define your domain
+  and business logic.
+
+  Contexts are also responsible for managing your data, regardless
+  if it comes from the database, an external API or others.
+  """
+end

lib/arcadia_cloud/application.ex

@@ -0,0 +1,32 @@
+defmodule ArcadiaCloud.Application do
+  # See https://hexdocs.pm/elixir/Application.html
+  # for more information on OTP Applications
+  @moduledoc false
+
+  use Application
+
+  @impl true
+  def start(_type, _args) do
+    children = [
+      ArcadiaCloudWeb.Telemetry,
+      ArcadiaCloud.Repo,
+      {DNSCluster, query: Application.get_env(:arcadia_cloud, :dns_cluster_query) || :ignore},
+      {Phoenix.PubSub, name: ArcadiaCloud.PubSub},
+      {Oban, Application.fetch_env!(:arcadia_cloud, Oban)},
+      ArcadiaCloudWeb.Endpoint
+    ]
+
+    # See https://hexdocs.pm/elixir/Supervisor.html
+    # for other strategies and supported options
+    opts = [strategy: :one_for_one, name: ArcadiaCloud.Supervisor]
+    Supervisor.start_link(children, opts)
+  end
+
+  # Tell Phoenix to update the endpoint configuration
+  # whenever the application is updated.
+  @impl true
+  def config_change(changed, _new, removed) do
+    ArcadiaCloudWeb.Endpoint.config_change(changed, removed)
+    :ok
+  end
+end

lib/arcadia_cloud/guardian.ex

@@ -0,0 +1,63 @@
+defmodule ArcadiaCloud.Guardian do
+  @moduledoc """
+  Verify-only Guardian implementation.
+
+  arcadia-cloud never issues tokens — that is arcadia-app's job. We only
+  decode and verify tokens minted by `Arcadia.Guardian`, then expose the
+  claims as a lightweight identity struct.
+
+  Token contract (set by arcadia-app):
+    sub          => "<user_id>:<tenant_id>"
+    tenant_id    => UUID string
+    tenant_slug  => string
+    email        => string
+    roles        => [string]
+  """
+
+  use Guardian, otp_app: :arcadia_cloud
+
+  def subject_for_token(%{"sub" => sub}, _claims) when is_binary(sub), do: {:ok, sub}
+  def subject_for_token(_resource, _claims), do: {:error, :not_token_issuer}
+
+  def resource_from_claims(claims) when is_map(claims) do
+    {user_id, tenant_id_from_sub} = parse_subject(claims["sub"])
+
+    {:ok,
+     %{
+       user_id: user_id,
+       tenant_id: claims["tenant_id"] || tenant_id_from_sub,
+       tenant_slug: claims["tenant_slug"],
+       email: claims["email"],
+       roles: claims["roles"] || []
+     }}
+  end
+
+  def resource_from_claims(_), do: {:error, :invalid_claims}
+
+  @doc """
+  Dev/test helper: mint a JWT using the local secret. Production tokens
+  are minted by arcadia-app.
+  """
+  def mint_dev_token(claims_overrides \\ %{}) do
+    defaults = %{
+      "sub" => "user-dev:tenant-dev",
+      "tenant_id" => "tenant-dev",
+      "tenant_slug" => "dev",
+      "email" => "dev@example.com",
+      "roles" => ["platform_admin"]
+    }
+
+    claims = Map.merge(defaults, claims_overrides)
+    {:ok, token, _claims} = encode_and_sign(claims, claims, token_type: :access)
+    {:ok, token}
+  end
+
+  defp parse_subject(nil), do: {nil, nil}
+
+  defp parse_subject(subject) when is_binary(subject) do
+    case String.split(subject, ":", parts: 2) do
+      [user_id, tenant_id] -> {user_id, tenant_id}
+      [user_id] -> {user_id, nil}
+    end
+  end
+end

lib/arcadia_cloud/repo.ex

@@ -0,0 +1,5 @@
+defmodule ArcadiaCloud.Repo do
+  use Ecto.Repo,
+    otp_app: :arcadia_cloud,
+    adapter: Ecto.Adapters.Postgres
+end

lib/arcadia_cloud_web.ex

@@ -0,0 +1,65 @@
+defmodule ArcadiaCloudWeb do
+  @moduledoc """
+  The entrypoint for defining your web interface, such
+  as controllers, components, channels, and so on.
+
+  This can be used in your application as:
+
+      use ArcadiaCloudWeb, :controller
+      use ArcadiaCloudWeb, :html
+
+  The definitions below will be executed for every controller,
+  component, etc, so keep them short and clean, focused
+  on imports, uses and aliases.
+
+  Do NOT define functions inside the quoted expressions
+  below. Instead, define additional modules and import
+  those modules here.
+  """
+
+  def static_paths, do: ~w(assets fonts images favicon.ico robots.txt)
+
+  def router do
+    quote do
+      use Phoenix.Router, helpers: false
+
+      # Import common connection and controller functions to use in pipelines
+      import Plug.Conn
+      import Phoenix.Controller
+    end
+  end
+
+  def channel do
+    quote do
+      use Phoenix.Channel
+    end
+  end
+
+  def controller do
+    quote do
+      use Phoenix.Controller, formats: [:html, :json]
+
+      use Gettext, backend: ArcadiaCloudWeb.Gettext
+
+      import Plug.Conn
+
+      unquote(verified_routes())
+    end
+  end
+
+  def verified_routes do
+    quote do
+      use Phoenix.VerifiedRoutes,
+        endpoint: ArcadiaCloudWeb.Endpoint,
+        router: ArcadiaCloudWeb.Router,
+        statics: ArcadiaCloudWeb.static_paths()
+    end
+  end
+
+  @doc """
+  When used, dispatch to the appropriate controller/live_view/etc.
+  """
+  defmacro __using__(which) when is_atom(which) do
+    apply(__MODULE__, which, [])
+  end
+end

lib/arcadia_cloud_web/controllers/error_json.ex

@@ -0,0 +1,21 @@
+defmodule ArcadiaCloudWeb.ErrorJSON do
+  @moduledoc """
+  This module is invoked by your endpoint in case of errors on JSON requests.
+
+  See config/config.exs.
+  """
+
+  # If you want to customize a particular status code,
+  # you may add your own clauses, such as:
+  #
+  # def render("500.json", _assigns) do
+  #   %{errors: %{detail: "Internal Server Error"}}
+  # end
+
+  # By default, Phoenix returns the status message from
+  # the template name. For example, "404.json" becomes
+  # "Not Found".
+  def render(template, _assigns) do
+    %{errors: %{detail: Phoenix.Controller.status_message_from_template(template)}}
+  end
+end

lib/arcadia_cloud_web/controllers/health_controller.ex

@@ -0,0 +1,7 @@
+defmodule ArcadiaCloudWeb.HealthController do
+  use ArcadiaCloudWeb, :controller
+
+  def show(conn, _params) do
+    json(conn, %{status: "ok", service: "arcadia-cloud"})
+  end
+end

lib/arcadia_cloud_web/controllers/inventory_controller.ex

@@ -0,0 +1,12 @@
+defmodule ArcadiaCloudWeb.InventoryController do
+  @moduledoc """
+  Cloud resource inventory. Phase 0 stub — returns an empty list.
+  Phase 1 wires this to `cloud_resources` filtered by tenant scope.
+  """
+
+  use ArcadiaCloudWeb, :controller
+
+  def index(conn, _params) do
+    json(conn, %{resources: []})
+  end
+end

lib/arcadia_cloud_web/endpoint.ex

@@ -0,0 +1,56 @@
+defmodule ArcadiaCloudWeb.Endpoint do
+  use Phoenix.Endpoint, otp_app: :arcadia_cloud
+
+  # The session will be stored in the cookie and signed,
+  # this means its contents can be read but not tampered with.
+  # Set :encryption_salt if you would also like to encrypt it.
+  @session_options [
+    store: :cookie,
+    key: "_arcadia_cloud_key",
+    signing_salt: "Ia2pTcnv",
+    same_site: "Lax"
+  ]
+
+  # socket "/live", Phoenix.LiveView.Socket,
+  #   websocket: [connect_info: [session: @session_options]],
+  #   longpoll: [connect_info: [session: @session_options]]
+
+  # Serve at "/" the static files from "priv/static" directory.
+  #
+  # When code reloading is disabled (e.g., in production),
+  # the `gzip` option is enabled to serve compressed
+  # static files generated by running `phx.digest`.
+  plug Plug.Static,
+    at: "/",
+    from: :arcadia_cloud,
+    gzip: not code_reloading?,
+    only: ArcadiaCloudWeb.static_paths(),
+    raise_on_missing_only: code_reloading?
+
+  # Code reloading can be explicitly enabled under the
+  # :code_reloader configuration of your endpoint.
+  if code_reloading? do
+    plug Phoenix.CodeReloader
+    plug Phoenix.Ecto.CheckRepoStatus, otp_app: :arcadia_cloud
+  end
+
+  plug Plug.RequestId
+  plug Plug.Telemetry, event_prefix: [:phoenix, :endpoint]
+
+  plug Plug.Parsers,
+    parsers: [:urlencoded, :multipart, :json],
+    pass: ["*/*"],
+    json_decoder: Phoenix.json_library()
+
+  plug Plug.MethodOverride
+  plug Plug.Head
+  plug Plug.Session, @session_options
+
+  plug CORSPlug,
+    origin: [
+      "http://localhost:5173",
+      ~r{^https://.*\.sky-ai\.com$}
+    ]
+
+  plug ArcadiaCloudWeb.Router
+end

lib/arcadia_cloud_web/gettext.ex

@@ -0,0 +1,25 @@
+defmodule ArcadiaCloudWeb.Gettext do
+  @moduledoc """
+  A module providing Internationalization with a gettext-based API.
+
+  By using [Gettext](https://hexdocs.pm/gettext), your module compiles translations
+  that you can use in your application. To use this Gettext backend module,
+  call `use Gettext` and pass it as an option:
+
+      use Gettext, backend: ArcadiaCloudWeb.Gettext
+
+      # Simple translation
+      gettext("Here is the string to translate")
+
+      # Plural translation
+      ngettext("Here is the string to translate",
+               "Here are the strings to translate",
+               3)
+
+      # Domain-based translation
+      dgettext("errors", "Here is the error message to translate")
+
+  See the [Gettext Docs](https://hexdocs.pm/gettext) for detailed usage.
+  """
+  use Gettext.Backend, otp_app: :arcadia_cloud
+end

lib/arcadia_cloud_web/plugs/require_auth.ex

@@ -0,0 +1,34 @@
+defmodule ArcadiaCloudWeb.Plugs.RequireAuth do
+  @moduledoc """
+  Validates a Bearer JWT issued by arcadia-app and assigns the resulting
+  identity + raw claims onto the conn. Halts with 401 on any failure.
+
+  Downstream controllers read `conn.assigns.current_identity` and, if
+  needed, `conn.assigns.current_claims`.
+  """
+
+  import Plug.Conn
+
+  alias ArcadiaCloud.Guardian
+
+  def init(opts), do: opts
+
+  def call(conn, _opts) do
+    with ["Bearer " <> token] <- get_req_header(conn, "authorization"),
+         {:ok, claims} <- Guardian.decode_and_verify(token),
+         {:ok, identity} <- Guardian.resource_from_claims(claims) do
+      conn
+      |> assign(:current_identity, identity)
+      |> assign(:current_claims, claims)
+    else
+      _ -> unauthorized(conn)
+    end
+  end
+
+  defp unauthorized(conn) do
+    conn
+    |> put_resp_content_type("application/json")
+    |> send_resp(401, Jason.encode!(%{error: "unauthorized"}))
+    |> halt()
+  end
+end

lib/arcadia_cloud_web/router.ex

@@ -0,0 +1,23 @@
+defmodule ArcadiaCloudWeb.Router do
+  use ArcadiaCloudWeb, :router
+
+  pipeline :api do
+    plug :accepts, ["json"]
+  end
+
+  pipeline :authed do
+    plug ArcadiaCloudWeb.Plugs.RequireAuth
+  end
+
+  scope "/api", ArcadiaCloudWeb do
+    pipe_through :api
+
+    get "/health", HealthController, :show
+  end
+
+  scope "/api/v1", ArcadiaCloudWeb do
+    pipe_through [:api, :authed]
+
+    get "/inventory", InventoryController, :index
+  end
+end

lib/arcadia_cloud_web/telemetry.ex

@@ -0,0 +1,93 @@
+defmodule ArcadiaCloudWeb.Telemetry do
+  use Supervisor
+  import Telemetry.Metrics
+
+  def start_link(arg) do
+    Supervisor.start_link(__MODULE__, arg, name: __MODULE__)
+  end
+
+  @impl true
+  def init(_arg) do
+    children = [
+      # Telemetry poller will execute the given period measurements
+      # every 10_000ms. Learn more here: https://hexdocs.pm/telemetry_metrics
+      {:telemetry_poller, measurements: periodic_measurements(), period: 10_000}
+      # Add reporters as children of your supervision tree.
+      # {Telemetry.Metrics.ConsoleReporter, metrics: metrics()}
+    ]
+
+    Supervisor.init(children, strategy: :one_for_one)
+  end
+
+  def metrics do
+    [
+      # Phoenix Metrics
+      summary("phoenix.endpoint.start.system_time",
+        unit: {:native, :millisecond}
+      ),
+      summary("phoenix.endpoint.stop.duration",
+        unit: {:native, :millisecond}
+      ),
+      summary("phoenix.router_dispatch.start.system_time",
+        tags: [:route],
+        unit: {:native, :millisecond}
+      ),
+      summary("phoenix.router_dispatch.exception.duration",
+        tags: [:route],
+        unit: {:native, :millisecond}
+      ),
+      summary("phoenix.router_dispatch.stop.duration",
+        tags: [:route],
+        unit: {:native, :millisecond}
+      ),
+      summary("phoenix.socket_connected.duration",
+        unit: {:native, :millisecond}
+      ),
+      sum("phoenix.socket_drain.count"),
+      summary("phoenix.channel_joined.duration",
+        unit: {:native, :millisecond}
+      ),
+      summary("phoenix.channel_handled_in.duration",
+        tags: [:event],
+        unit: {:native, :millisecond}
+      ),
+
+      # Database Metrics
+      summary("arcadia_cloud.repo.query.total_time",
+        unit: {:native, :millisecond},
+        description: "The sum of the other measurements"
+      ),
+      summary("arcadia_cloud.repo.query.decode_time",
+        unit: {:native, :millisecond},
+        description: "The time spent decoding the data received from the database"
+      ),
+      summary("arcadia_cloud.repo.query.query_time",
+        unit: {:native, :millisecond},
+        description: "The time spent executing the query"
+      ),
+      summary("arcadia_cloud.repo.query.queue_time",
+        unit: {:native, :millisecond},
+        description: "The time spent waiting for a database connection"
+      ),
+      summary("arcadia_cloud.repo.query.idle_time",
+        unit: {:native, :millisecond},
+        description:
+          "The time the connection spent waiting before being checked out for the query"
+      ),
+
+      # VM Metrics
+      summary("vm.memory.total", unit: {:byte, :kilobyte}),
+      summary("vm.total_run_queue_lengths.total"),
+      summary("vm.total_run_queue_lengths.cpu"),
+      summary("vm.total_run_queue_lengths.io")
+    ]
+  end
+
+  defp periodic_measurements do
+    [
+      # A module, function and arguments to be invoked periodically.
+      # This function must call :telemetry.execute/3 and a metric must be added above.
+      # {ArcadiaCloudWeb, :count_users, []}
+    ]
+  end
+end