> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openinary.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Project Structure

> Where everything lives in the Openinary monorepo, and which package owns what.

Openinary is a **pnpm monorepo** orchestrated by [Turbo](https://turbo.build/). It
holds both the AGPL-3.0 self-hosted product and the source of the managed Cloud
service, so a fix to the shared engine lands in both at once. The engine itself is
`packages/core`, not `apps/api`.

```bash theme={null}
openinary/
├── apps/
│   ├── api/          # Hono.js media processing API         (AGPL-3.0)
│   ├── web/          # Next.js admin dashboard              (AGPL-3.0)
│   ├── telemetry/    # Anonymous self-host telemetry worker (AGPL-3.0)
│   ├── marketing/    # openinary.dev                        (MIT)
│   ├── docs/         # This documentation
│   └── cloud/        # Openinary Cloud, see apps/cloud/LICENSE
│       ├── server/   #   API worker + media container
│       ├── web/      #   Customer dashboard
│       └── admin/    #   Back office
├── packages/         # core, ui, cli, registry, shared      (AGPL-3.0)
├── docker/           # Optimized Dockerfiles
├── scripts/          # Release, env bootstrap, database hardening
└── docker-compose.yml
```

Everything is AGPL-3.0 except `apps/cloud/`, which is source-available under a
commercial license, and `apps/marketing/`, which is MIT. Self-hosting needs
nothing from `apps/cloud/`.

## packages/

| Package | What it is |
| - | - |
| `@openinary/core` | The transformation engine: image and video pipelines, storage clients, the job queue. Used by `apps/api` and by the Cloud's media container. |
| `@openinary/ui` | React components, including the file uploader. |
| `create-openinary` | The CLI (`npx create-openinary`), published to npm. |
| `registry` | shadcn/ui registry source. Builds into `apps/marketing/public/r`, which is what serves `openinary.dev/r`. The output is generated, not committed. |
| `shared` | Auth config, database instance and shared types for the self-hosted apps. |

The apps consume `core` and `ui` through `workspace:*`, so nothing has to be
published between fixing something and shipping it. Both were published to npm up
to `@openinary/core` 1.6.0 and `@openinary/ui` 0.8.1, and both are marked
`private` now, so those versions are frozen. To use them in your own app, go
through the [shadcn registry](https://docs.openinary.dev/guides/file-uploader.md).

## packages/core

Nearly all media, storage and queue logic lives here rather than in `apps/api`.
That is what lets the self-hosted API and the Cloud's media container share one
implementation.

```bash theme={null}
packages/core/src/
├── routes/           # transform, authenticated, storage, queue, download, invalidate, video-status
├── services/         # TransformService, the entry point for every delivery request
└── utils/
    ├── image/        # Sharp-based image pipeline
    ├── video/        # FFmpeg pipeline, job queue and SQLite job store
    ├── storage/      # S3-compatible client (AWS, R2, MinIO…)
    ├── cache.ts      # Cache path resolution and lookups
    ├── parser.ts     # URL transformation parameter parser
    ├── signature.ts  # HMAC-SHA256 signed URL generation and verification
    └── upload-validation.ts  # Accepted types and magic-byte checks
```

**Key dependencies:** `sharp`, `fluent-ffmpeg`, `@aws-sdk/client-s3`, `@webtoon/psd`, `fflate`, `hono`, `better-sqlite3`, `pino`

## apps/api

The self-hosted server. It wires the engine to HTTP: startup, auth, rate limiting,
and the three routes specific to a self-hosted instance. Everything else is
mounted from `@openinary/core`.

```bash theme={null}
apps/api/src/
├── routes/           # api-keys, health, upload
├── middleware/       # apiKeyAuth, rate limiting, presigned upload auth
├── config/           # STORAGE_* resolution, queue wiring
└── utils/            # Database init, telemetry
```

**Key dependencies:** `hono`, `@openinary/core`, `shared`, `better-sqlite3`, `heic-convert`, `zod`

## apps/web

The Next.js 15 admin dashboard, for uploads, API keys and video queue status.

```bash theme={null}
apps/web/src/app/
├── (dashboard)/      # Protected dashboard routes (requires login)
│   ├── page.tsx      # Media browser
│   ├── api-keys/     # API key management
│   └── debug/queue/  # Video queue inspector
├── login/            # Login page
├── setup/            # First-run admin account creation
├── uploader-demo/    # File uploader playground
└── api/
    ├── auth/         # Better Auth handler
    ├── check-setup/  # Whether first-run setup is still pending
    ├── upload-token/ # Mints presigned upload signatures for the demo
    └── version/      # Running version, used by the update banner
```

**Key dependencies:** `next`, `react`, `@tanstack/react-query`, `better-auth`, Radix UI, Tailwind CSS v4

## packages/shared

Consumed by both `api` and `web`. It keeps auth configuration and the SQLite
instance in one place, so both apps always use the same database.

```bash theme={null}
packages/shared/src/
├── auth.ts             # Better Auth config, API key plugin, and the SQLite instance
├── auth-client.ts      # Client-side auth helpers
├── auth-client-only.ts # Browser-only entry point
├── types.ts            # Shared TypeScript types
└── index.ts
```

The SQLite instance is created inside `auth.ts`; there is no separate `db.ts`.
Both apps import through the `"shared"` and `"shared/*"` path aliases defined in
`packages/shared/package.json`.

## Dependency flow

```
api  →  @openinary/core  →  sharp, fluent-ffmpeg, @aws-sdk/client-s3
api  →  shared           →  better-auth, @better-auth/api-key, better-sqlite3
web  →  @openinary/ui
web  →  shared
```

## Next steps

> [card] [Local Development](https://docs.openinary.dev/local-development.md)
>
> Run the monorepo locally with pnpm.

> [card] [Security](https://docs.openinary.dev/security.md)
>
> Auth architecture, API keys, and route reference.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.