Getting Started

A practical guide to running the HVC platform locally. Read the Architecture and Tech Stack pages first for context.

Prerequisites

Tool	Version	Used by
Node.js + pnpm	Node 18+ / pnpm 8+	hippo-portal, hvc-admin-web, hvc-docs
.NET SDK	6, 7, 8	Backend services (hvc-api, hvc-admin-api, hvc-services, hvc-sinkapi, ...)
Flutter (FVM)	3.41 (mobile), 3.0 (headset)	hvcmobile, hvc-xr
SQL Server	local or container	Tenant + admin databases
Docker (optional)	—	Storage emulator / local infra

Repo layout

The codebase is split across two trees: the backend + other clients live under hippo/, and the web client lives in its own repo (hippo-portal).

hippo/
├── hvc-api            # Main client-facing API (.NET 7)
├── hvc-admin-api      # Admin/back-office API (.NET 7)
├── hvc-admin-web      # Admin console (SvelteKit)
├── hvcmobile          # Mobile client (Flutter)
├── hvc-xr             # Headset client (Flutter/RealWear)
├── hvc-services       # Email + recording worker (.NET 8)
├── hvc-ws             # WebSocket presence (.NET 8)
├── hvc-sinkapi        # Meeting finalizer (.NET 7)
├── hvc-filePushApi    # Recording file pusher (.NET 8)
├── hvc-webLogger      # Browser log ingestion (.NET 7)
├── hvc-storage        # Storage abstraction library
├── hvc-shared         # Shared helpers library
├── StorageEmulator    # Local Azure Blob emulator project
└── hvc-docs           # This documentation site (VitePress)

hippo2/Frontend/
├── hvcweb             # Web portal ("hippo-portal", SvelteKit + Houdini)
└── hvcdeploy          # Deployment configuration

Running the docs

cd hvc-docs
pnpm install
pnpm docs:dev     # http://localhost:5173
pnpm docs:build   # static build (CI)

Running the web client

The web portal lives in hippo2/Frontend/hvcweb (a SvelteKit SPA).

cd hippo2/Frontend/hvcweb
pnpm install
pnpm dev:local       # local backend
pnpm dev:myhippo.io  # multi-tenant (https://{domain}.my-hippo.io)
pnpm dev             # mode=test

The portal needs the backend (hvc-api) + Keycloak to log in. Environment config comes from .env.* files (PUBLIC_SERVER_URL, PUBLIC_KEYCLOAK_URL, PUBLIC_KEYCLOAK_CLIENTID, PUBLIC_WS_URL), and the GraphQL schema is generated with Houdini (schema.graphql + pnpm run pull equivalent) into .houdini/.

Running the backend services

Most .NET services read a shared, non-committed config folder. Set:

$env:DEV_CONFIG_PATH = "C:\path\to\your\config"   # folder containing hvc/*-config/

The expected layout (per service):

{DEV_CONFIG_PATH}/hvc/services-config/appsettings.json     # hvc-services
{DEV_CONFIG_PATH}/hvc/sink-config/appsettings.dev.json     # hvc-sinkapi
{DEV_CONFIG_PATH}/hvc/filepush-config/appsettings.json     # hvc-filePushApi

Then run with dotnet run (or the solution hvc.sln in Visual Studio). Each service loads the matching file in development automatically. This is needed only for local dev.

Required infrastructure

• SQL Server — tenant + admin databases (connection strings come from config).
• Keycloak — identity provider; realms per tenant (see Api — Auth).
• Pexip Infinity — conferencing (VMR creation + telemetry).
• Object storage — Azure Blob / MinIO / S3 via hvc-storage (or local disk with storeType: file).
• Seq — centralized logs (optional locally).
• StorageEmulator — a local Azure Blob emulator project in the repo, useful when developing the recording/file pipeline without real Azure.

Where to look next

• Services — how the workers fit together + troubleshooting.
• Api — the main API and its feature areas.
• Data model — the main tables.
• Permissions — what each permission gates.
• Glossary — terms used across the platform.