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_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