# neuro-inc/launchpad architecture

> Architecture diagram of the GitHub repository neuro-inc/launchpad, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/neuro-inc/launchpad
- Repository: https://github.com/neuro-inc/launchpad

## Overview

Launchpad exposes authenticated APIs for app templates and instances, then coordinates template metadata, app installation/import, and instance management through its service layer and the external Apps API. OAuth/Keycloak and static-hostname authentication support access to the platform. The graph also preserves the built-in app registry and template persistence. Several connections are supported by the SOURCE INDEX or README; unsampled runtime details are not inferred beyond those references.

Main entry points: [`launchpad/apps/service.py`](https://github.com/neuro-inc/launchpad/blob/master/launchpad/apps/service.py) (App service), [`launchpad/apps/registry/__init__.py`](https://github.com/neuro-inc/launchpad/blob/master/launchpad/apps/registry/__init__.py) (App registry), [`launchpad/apps/template_storage.py`](https://github.com/neuro-inc/launchpad/blob/master/launchpad/apps/template_storage.py) (Template storage), [`launchpad/apps/api.py`](https://github.com/neuro-inc/launchpad/blob/master/launchpad/apps/api.py) (App routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and authentication"]
  node_api_routes["HTTP routes<br/>[api.py]"]
  node_app_routes["App routes<br/>[api.py]"]
  node_auth_routes["Auth routes<br/>[api.py]"]
  node_auth_dependencies["Auth checks<br/>[dependencies.py]"]
  node_oauth["OAuth flow<br/>[oauth.py]"]
  node_static_auth["Hostname sessions<br/>[static_hostname.py]"]
end

subgraph group_apps["App lifecycle"]
  node_app_service["App service<br/>[service.py]"]
  node_app_records["App records<br/>[storage.py]"]
  node_app_models["App models<br/>[models.py]"]
end

subgraph group_registry["Templates and registry"]
  node_template_storage["Template storage"]
  node_template_models["Template models<br/>[template_models.py]"]
  node_registry["App registry<br/>[__init__.py]"]
  node_registry_base["App definitions<br/>[base.py]"]
  node_app_context["Input context<br/>[context.py]"]
  node_embeddings["Embeddings app<br/>[embeddings.py]"]
  node_llm["LLM inference app<br/>[llm_inference.py]"]
  node_postgres_app["Postgres app<br/>[postgres.py]"]
  node_openwebui["OpenWebUI app<br/>[openwebui.py]"]
end

subgraph group_platform["Platform and persistence"]
  node_apps_api["Apps API client<br/>[apps_api.py]"]
  node_app_configurator["App configurator"]
  node_platform_api["Launchpad API client<br/>[launchpad_api.py]"]
  node_db_models["Database base<br/>[base.py]"]
  node_database[("SQL database")]
end

node_user(("API client"))
node_keycloak["Keycloak"]
node_apps_platform["Apolo Apps API"]

node_user -->|"sends requests"| node_api_routes
node_api_routes -->|"routes app requests"| node_app_routes
node_api_routes -->|"routes auth requests"| node_auth_routes
node_app_routes -->|"checks access"| node_auth_dependencies
node_app_routes -->|"delegates app operations"| node_app_service
node_app_routes -->|"uses template storage"| node_template_storage
node_auth_routes -->|"uses OAuth"| node_oauth
node_auth_routes -->|"uses hostname auth"| node_static_auth
node_auth_dependencies -->|"decodes OAuth tokens"| node_oauth
node_auth_dependencies -->|"checks hostname sessions"| node_static_auth
node_oauth -->|"fetches tokens"| node_keycloak
node_app_service -->|"manages instances"| node_apps_api
node_app_service -->|"reads and writes"| node_app_records
node_app_service -->|"looks up templates"| node_template_storage
node_app_service -->|"selects app definitions"| node_registry
node_app_service -->|"builds app context"| node_app_context
node_app_service -->|"uses platform client"| node_platform_api
node_template_storage -->|"queries templates"| node_template_models
node_template_storage -->|"checks installed apps"| node_app_records
node_template_storage -.->|"persists templates"| node_database
node_registry -->|"registers definitions"| node_registry_base
node_registry -->|"registers app"| node_embeddings
node_registry -->|"registers app"| node_llm
node_registry -->|"registers app"| node_postgres_app
node_registry -->|"registers app"| node_openwebui
node_embeddings -->|"merges inputs"| node_app_context
node_llm -->|"merges inputs"| node_app_context
node_registry_base -->|"provides context contract"| node_app_context
node_app_models -->|"uses database base"| node_db_models
node_template_models -->|"uses database base"| node_db_models
node_apps_api -->|"sends API requests"| node_apps_platform
node_app_configurator -->|"uses API client"| node_apps_api

click node_api_routes "https://github.com/neuro-inc/launchpad/blob/master/launchpad/api.py"
click node_app_routes "https://github.com/neuro-inc/launchpad/blob/master/launchpad/apps/api.py"
click node_auth_routes "https://github.com/neuro-inc/launchpad/blob/master/launchpad/auth/api.py"
click node_auth_dependencies "https://github.com/neuro-inc/launchpad/blob/master/launchpad/auth/dependencies.py"
click node_oauth "https://github.com/neuro-inc/launchpad/blob/master/launchpad/auth/oauth.py"
click node_static_auth "https://github.com/neuro-inc/launchpad/blob/master/launchpad/auth/static_hostname.py"
click node_app_service "https://github.com/neuro-inc/launchpad/blob/master/launchpad/apps/service.py"
click node_app_records "https://github.com/neuro-inc/launchpad/blob/master/launchpad/apps/storage.py"
click node_app_models "https://github.com/neuro-inc/launchpad/blob/master/launchpad/apps/models.py"
click node_template_storage "https://github.com/neuro-inc/launchpad/blob/master/launchpad/apps/template_storage.py"
click node_template_models "https://github.com/neuro-inc/launchpad/blob/master/launchpad/apps/template_models.py"
click node_registry "https://github.com/neuro-inc/launchpad/blob/master/launchpad/apps/registry/__init__.py"
click node_registry_base "https://github.com/neuro-inc/launchpad/blob/master/launchpad/apps/registry/base.py"
click node_app_context "https://github.com/neuro-inc/launchpad/blob/master/launchpad/apps/registry/internal/context.py"
click node_embeddings "https://github.com/neuro-inc/launchpad/blob/master/launchpad/apps/registry/internal/embeddings.py"
click node_llm "https://github.com/neuro-inc/launchpad/blob/master/launchpad/apps/registry/internal/llm_inference.py"
click node_postgres_app "https://github.com/neuro-inc/launchpad/blob/master/launchpad/apps/registry/internal/postgres.py"
click node_openwebui "https://github.com/neuro-inc/launchpad/blob/master/launchpad/apps/registry/shared/openwebui.py"
click node_apps_api "https://github.com/neuro-inc/launchpad/blob/master/launchpad/ext/apps_api.py"
click node_app_configurator "https://github.com/neuro-inc/launchpad/blob/master/launchpad/ext/app_configurator.py"
click node_platform_api "https://github.com/neuro-inc/launchpad/blob/master/launchpad/ext/launchpad_api.py"
click node_db_models "https://github.com/neuro-inc/launchpad/blob/master/launchpad/db/base.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api_routes,node_app_routes,node_auth_routes,node_auth_dependencies,node_oauth,node_static_auth,node_user toneBlue
class node_app_service,node_app_records,node_app_models toneAmber
class node_template_storage,node_template_models,node_registry,node_registry_base,node_app_context,node_embeddings,node_llm,node_postgres_app,node_openwebui,node_apps_platform toneMint
class node_apps_api,node_app_configurator,node_platform_api,node_db_models,node_database toneRose
class node_keycloak toneIndigo
```

## Components

### API and authentication

- [HTTP routes](https://github.com/neuro-inc/launchpad/blob/master/launchpad/api.py): `launchpad/api.py`
- [App routes](https://github.com/neuro-inc/launchpad/blob/master/launchpad/apps/api.py): `launchpad/apps/api.py`
- [Auth routes](https://github.com/neuro-inc/launchpad/blob/master/launchpad/auth/api.py): `launchpad/auth/api.py`
- [Auth checks](https://github.com/neuro-inc/launchpad/blob/master/launchpad/auth/dependencies.py): `launchpad/auth/dependencies.py`
- [OAuth flow](https://github.com/neuro-inc/launchpad/blob/master/launchpad/auth/oauth.py): `launchpad/auth/oauth.py`
- [Hostname sessions](https://github.com/neuro-inc/launchpad/blob/master/launchpad/auth/static_hostname.py): `launchpad/auth/static_hostname.py`

### App lifecycle

- [App service](https://github.com/neuro-inc/launchpad/blob/master/launchpad/apps/service.py): `launchpad/apps/service.py`
- [App records](https://github.com/neuro-inc/launchpad/blob/master/launchpad/apps/storage.py): `launchpad/apps/storage.py`
- [App models](https://github.com/neuro-inc/launchpad/blob/master/launchpad/apps/models.py): `launchpad/apps/models.py`

### Templates and registry

- [Template storage](https://github.com/neuro-inc/launchpad/blob/master/launchpad/apps/template_storage.py): `launchpad/apps/template_storage.py`
- [Template models](https://github.com/neuro-inc/launchpad/blob/master/launchpad/apps/template_models.py): `launchpad/apps/template_models.py`
- [App registry](https://github.com/neuro-inc/launchpad/blob/master/launchpad/apps/registry/__init__.py): `launchpad/apps/registry/__init__.py`
- [App definitions](https://github.com/neuro-inc/launchpad/blob/master/launchpad/apps/registry/base.py): `launchpad/apps/registry/base.py`
- [Input context](https://github.com/neuro-inc/launchpad/blob/master/launchpad/apps/registry/internal/context.py): `launchpad/apps/registry/internal/context.py`
- [Embeddings app](https://github.com/neuro-inc/launchpad/blob/master/launchpad/apps/registry/internal/embeddings.py): `launchpad/apps/registry/internal/embeddings.py`
- [LLM inference app](https://github.com/neuro-inc/launchpad/blob/master/launchpad/apps/registry/internal/llm_inference.py): `launchpad/apps/registry/internal/llm_inference.py`
- [Postgres app](https://github.com/neuro-inc/launchpad/blob/master/launchpad/apps/registry/internal/postgres.py): `launchpad/apps/registry/internal/postgres.py`
- [OpenWebUI app](https://github.com/neuro-inc/launchpad/blob/master/launchpad/apps/registry/shared/openwebui.py): `launchpad/apps/registry/shared/openwebui.py`

### Platform and persistence

- [Apps API client](https://github.com/neuro-inc/launchpad/blob/master/launchpad/ext/apps_api.py): `launchpad/ext/apps_api.py`
- [App configurator](https://github.com/neuro-inc/launchpad/blob/master/launchpad/ext/app_configurator.py): `launchpad/ext/app_configurator.py`
- [Launchpad API client](https://github.com/neuro-inc/launchpad/blob/master/launchpad/ext/launchpad_api.py): `launchpad/ext/launchpad_api.py`
- [Database base](https://github.com/neuro-inc/launchpad/blob/master/launchpad/db/base.py): `launchpad/db/base.py`
- **SQL database**

### Other components

- **API client**
- **Keycloak**
- **Apolo Apps API**

## Connections

- API client → HTTP routes: sends requests
- HTTP routes → App routes: routes app requests (evidence: `launchpad/api.py`)
- HTTP routes → Auth routes: routes auth requests (evidence: `launchpad/api.py`)
- App routes → Auth checks: checks access (evidence: `launchpad/apps/api.py`)
- App routes → App service: delegates app operations (evidence: `launchpad/apps/api.py`)
- App routes → Template storage: uses template storage (evidence: `launchpad/apps/api.py`)
- Auth routes → OAuth flow: uses OAuth (evidence: `launchpad/auth/api.py`)
- Auth routes → Hostname sessions: uses hostname auth (evidence: `launchpad/auth/api.py`)
- Auth checks → OAuth flow: decodes OAuth tokens (evidence: `launchpad/auth/dependencies.py`)
- Auth checks → Hostname sessions: checks hostname sessions (evidence: `launchpad/auth/dependencies.py`)
- OAuth flow → Keycloak: fetches tokens (evidence: `launchpad/auth/oauth.py`)
- App service → Apps API client: manages instances (evidence: `launchpad/apps/service.py`)
- App service → App records: reads and writes (evidence: `launchpad/apps/service.py`)
- App service → Template storage: looks up templates (evidence: `launchpad/apps/service.py`)
- App service → App registry: selects app definitions (evidence: `launchpad/apps/service.py`)
- App service → Input context: builds app context (evidence: `launchpad/apps/service.py`)
- App service → Launchpad API client: uses platform client (evidence: `launchpad/apps/service.py`)
- Template storage → Template models: queries templates (evidence: `launchpad/apps/template_storage.py`)
- Template storage → App records: checks installed apps (evidence: `launchpad/apps/template_storage.py`)
- Template storage → SQL database: persists templates
- App registry → App definitions: registers definitions (evidence: `launchpad/apps/registry/__init__.py`)
- App registry → Embeddings app: registers app (evidence: `launchpad/apps/registry/__init__.py`)
- App registry → LLM inference app: registers app (evidence: `launchpad/apps/registry/__init__.py`)
- App registry → Postgres app: registers app (evidence: `launchpad/apps/registry/__init__.py`)
- App registry → OpenWebUI app: registers app (evidence: `launchpad/apps/registry/__init__.py`)
- Embeddings app → Input context: merges inputs (evidence: `launchpad/apps/registry/internal/embeddings.py`)
- LLM inference app → Input context: merges inputs (evidence: `launchpad/apps/registry/internal/llm_inference.py`)
- App definitions → Input context: provides context contract (evidence: `launchpad/apps/registry/internal/context.py`)
- App models → Database base: uses database base (evidence: `launchpad/apps/models.py`)
- Template models → Database base: uses database base (evidence: `launchpad/apps/template_models.py`)
- Apps API client → Apolo Apps API: sends API requests
- App configurator → Apps API client: uses API client (evidence: `launchpad/ext/app_configurator.py`)
