This document provides a high-level introduction to the Unraid API repository and its architecture. It covers the monorepo structure, core packages, technology stack, and deployment model. For detailed information about specific subsystems, see:
The Unraid API is a modern management interface for Unraid servers that provides programmatic access to system resources through a GraphQL API and a Vue.js-based web interface. It is distributed as an Unraid plugin (.plg file) that installs onto Unraid OS 6.12.15 and later.
Primary Functions:
Target Users:
Sources: README.md api/package.json1-238 plugin/package.json1-47
The repository is organized as a pnpm workspace monorepo containing multiple interdependent packages. The root-level package.json1-79 defines workspace scripts that orchestrate building, testing, and deployment across all packages.
Key Package Roles:
| Package | Path | Purpose | Entry Point |
|---|---|---|---|
@unraid/api | api/ | Backend GraphQL server | api/src/index.ts1-194 |
@unraid/web | web/ | Frontend Vue.js application | web/src/main.ts |
@unraid/ui | unraid-ui/ | Reusable Vue components | unraid-ui/package.json121-128 |
@unraid/connect-plugin | plugin/ | Plugin packaging scripts | plugin/builder/build-txz.ts |
unraid-api-plugin-connect | packages/unraid-api-plugin-connect/ | Connect service module | packages/unraid-api-plugin-connect/package.json1-105 |
@unraid/shared | packages/unraid-shared/ | Shared TypeScript utilities | packages/unraid-shared/package.json1-75 |
The monorepo uses pnpm workspaces for dependency management with version pinning enforced at the root pnpm-lock.yaml1-891016 All packages share common versions of [email protected], @nestjs/*@11.1.6, and [email protected].
Sources: package.json1-79 pnpm-lock.yaml1-10 api/package.json1-238 web/package.json1-153 unraid-ui/package.json1-130
The API backend uses the following key technologies and frameworks:
Web Framework Stack:
@nestjs/[email protected]): Dependency injection framework, decorators, module system[email protected]): HTTP server via @nestjs/[email protected]@apollo/[email protected]): GraphQL server integrated via @as-integrations/[email protected]GraphQL Tooling:
@graphql-codegen/[email protected]): Generates TypeScript types from schema[email protected]): WebSocket transport for subscriptions[email protected]): PubSub system for real-time eventsAuthentication & Authorization:
@nestjs/[email protected]): Authentication strategies[email protected]): RBAC authorization via [email protected][email protected]): OpenID Connect authenticationSystem Integration:
[email protected]): Docker API client@unraid/[email protected]): VM management via libvirt bindings[email protected]): File system watching[email protected]): System metrics collectionProcess Management:
[email protected]): Process lifecycle management defined in api/ecosystem.config.jsonSources: api/package.json57-153 api/src/index.ts1-194
The web application uses the following technologies:
UI Framework:
[email protected]): Reactive UI framework[email protected]): Utility-first styling via @tailwindcss/[email protected]GraphQL Client:
@apollo/[email protected]): GraphQL client with caching@vue/[email protected]): Vue 3 composition API integrationState Management:
[email protected]): Vue 3 state managementComponent Libraries:
[email protected]@headlessui/[email protected]): Unstyled accessible components@heroicons/[email protected]): SVG icon librarySources: web/package.json101-148 unraid-ui/package.json49-69
The following diagram shows the runtime architecture and how data flows through the system using actual class and service names from the codebase:
Key Components and Their Roles:
| Component | File/Class | Purpose |
|---|---|---|
viteNodeApp() | api/src/index.ts47-191 | Main entry point, initializes Redux store, loads config |
bootstrapNestServer() | api/src/unraid-api/main.ts | Creates NestJS application with Fastify adapter |
FastifyAdapter | @nestjs/platform-fastify | HTTP server wrapper for NestJS |
ApolloServer | Integrated via @nestjs/apollo | GraphQL schema execution engine |
PassportModule | @nestjs/passport | Routes auth to appropriate strategy |
CasbinModule | nest-authz | RBAC permission checking |
DockerService | api/src/unraid-api/docker/docker.service.ts | Docker container management |
VmService | api/src/unraid-api/vm/vm.service.ts | Virtual machine operations |
NotificationService | api/src/unraid-api/notifications/ | INI-based notification system |
Sources: api/src/index.ts47-191 api/package.json57-153 Diagram 2 from system architecture overview
All frontend-backend communication occurs through a strongly-typed GraphQL API. The schema is code-first (defined using NestJS decorators) and TypeScript types are auto-generated for both client and server.
Code Generation Workflow:
Example Type Safety:
@ObjectType() class Container with @Field() decoratorspnpm codegen in api/ generates TypeScript resolver typespnpm codegen in web/ generates typed query hooksuseQuery<ContainersQuery>(CONTAINERS_QUERY) with full type safetyThe generated code lives in api/src/generated/graphql.ts and web/src/generated/graphql.ts, ensuring frontend and backend types always match.
Sources: api/package.json30-32 web/package.json35-37 pnpm-lock.yaml52-54
The entire system is packaged as an Unraid plugin that installs onto Unraid OS. The plugin consists of:
.plg XML file): Declares version, dependencies, installation steps.txz file): Contains all application filesInstallation Paths:
| Component | Installation Path | Purpose |
|---|---|---|
| API Server | /usr/local/unraid-api/ | NestJS application bundle |
| Web Components | /usr/local/emhttp/plugins/dynamix.unraid.net/ | Vue.js web components |
| RC Scripts | /etc/rc.d/rc.unraid-api | Service control script |
| PM2 Config | /usr/local/unraid-api/ecosystem.config.json | Process manager config |
| Configuration | /boot/config/plugins/unraid-api/ | Persistent user config |
The plugin builder is located at plugin/builder/ with key scripts:
.txz archive from built packages.plg XML manifest with version and checksumsSources: plugin/package.json19-24 Diagram 4 from system architecture overview
The backend uses NestJS's dependency injection system extensively. Services are organized into feature modules that can be loaded dynamically:
DynamicModule.forRootAsync()Example plugin loading pattern from api/src/unraid-api/main.ts:
The system uses a hybrid state management approach:
Redux Store (deprecated, being phased out): api/src/store/
GraphQL Subscriptions: Real-time updates for dynamic data
PubSubEngine from graphql-subscriptionsApollo Cache (frontend): Client-side normalized cache
web/src/apollo/client.tsPinia Store (frontend): Local UI state
[email protected]Most configuration lives in INI files on the Unraid boot drive:
File watchers (using [email protected]) detect changes and emit Redux actions, which trigger GraphQL subscription updates to connected clients.
Sources: api/src/index.ts1-194 api/package.json57-153 api/dev/states/myservers.cfg1-25 Diagram 5 from system architecture overview
The monorepo uses automated semantic versioning via release-please:
4.29.2 as of the latest changelog entry in api/CHANGELOG.md1-9The plugin manifest always references the version from package.json to ensure consistency between the Node.js app and the Unraid plugin.
Sources: .release-please-manifest.json1-2 api/CHANGELOG.md1-20 package.json2-4
The Unraid API is a full-stack TypeScript application packaged as an Unraid plugin. It provides:
.plg packagingFor deeper dives into specific subsystems, proceed to the subsequent sections of this wiki.
Refresh this wiki