# Architectural Overview of Logto: Monorepo Structure and Component Breakdown

> Explore Logto's monorepo architecture. Understand its Koa.js OIDC backend, React UIs, PostgreSQL database, and pluggable connectors for seamless authentication.

- Repository: [Logto/logto](https://github.com/logto-io/logto)
- Tags: architecture
- Published: 2026-07-06

---

**Logto is a TypeScript-based monorepo organized into npm workspaces that combines a Koa.js OIDC/OAuth 2.1 backend, PostgreSQL database layer, React-based admin and experience UIs, and pluggable connectors for social/SMS/email authentication.**

This architectural overview of Logto examines how the identity platform structures its codebase across distinct runtime concerns. The repository uses **npm workspaces** to separate backend services, frontend applications, database schemas, and shared utilities while maintaining a unified build pipeline and TypeScript implementation.

## Monorepo Organization and Workspace Structure

Logto adopts a **monorepo** architecture where all components share a single TypeScript codebase and dependency tree. The repository organizes functionality into npm workspaces, each encapsulating a specific domain such as authentication logic, database schemas, or user interfaces.

Key workspace categories include:

- **Core services** handling OIDC/OAuth flows and management APIs
- **Database packages** defining PostgreSQL schemas and migration scripts
- **Frontend applications** built with React and Vite
- **Pluggable connectors** for external identity providers
- **Shared toolkits** providing common utilities across the stack

## Core Backend Architecture

The **backend core** (`@logto/core`) implements the complete OIDC/OAuth 2.1 provider and management API. Built on **Koa.js**, this layer handles all server-side business logic, token issuance, and tenant isolation.

The Core service exposes two primary ports:

- Port `3001` for user-facing OpenID Connect endpoints
- Port `3002` for administrative API operations

To start the Core in development mode:

```bash

# Ensure PostgreSQL is running and DB_URL is set

export DB_URL="postgres://postgres:p0stgr3s@localhost:5432/logto"

# Install dependencies and launch the Core

pnpm i
pnpm dev          # starts Core on http://localhost:3001 (user) and http://localhost:3002 (admin)

```

Key source files include:

- [`packages/core/src/index.ts`](https://github.com/logto-io/logto/blob/main/packages/core/src/index.ts) – Application entry point that initializes the Koa server and OIDC provider
- [`packages/core/src/routes.ts`](https://github.com/logto-io/logto/blob/main/packages/core/src/routes.ts) – Route definitions for authentication and management endpoints
- [`packages/core/package.json`](https://github.com/logto-io/logto/blob/main/packages/core/package.json) – Dependency configuration including `oidc-provider` library

## Database Schema and Migration System

Data persistence relies on **PostgreSQL**, with schema definitions and type safety managed through the `@logto/schemas` package. This workspace contains SQL migration files, alteration scripts, and TypeScript interfaces that mirror the database structure.

Critical files in this layer:

- [`packages/schemas/src/alterations/001_initial.sql`](https://github.com/logto-io/logto/blob/main/packages/schemas/src/alterations/001_initial.sql) – Initial database migration
- [`packages/schemas/src/foundations/types.ts`](https://github.com/logto-io/logto/blob/main/packages/schemas/src/foundations/types.ts) – TypeScript type definitions for database entities
- [`packages/schemas/package.json`](https://github.com/logto-io/logto/blob/main/packages/schemas/package.json) – Schema package configuration

The Core service connects to PostgreSQL via the `DB_URL` environment variable, loading schema definitions at startup to ensure type-safe database interactions.

## Frontend Applications: Admin Console and Experience

Logto provides two distinct React-based single-page applications (SPAs), both built with **Vite** for rapid development cycles.

### Admin Console

The **Admin Console** (`@logto/console`) serves as the management dashboard where administrators configure tenants, applications, and access policies. It authenticates against the Core's management API (port `3002`) using service-account tokens.

Key implementation files:

- [`packages/console/src/App.tsx`](https://github.com/logto-io/logto/blob/main/packages/console/src/App.tsx) – Root application component
- [`packages/console/src/pages/Dashboard.tsx`](https://github.com/logto-io/logto/blob/main/packages/console/src/pages/Dashboard.tsx) – Main dashboard interface
- [`packages/console/package.json`](https://github.com/logto-io/logto/blob/main/packages/console/package.json) – Frontend dependencies and build configuration

The console typically runs on port `5002` during development.

### Experience UI

The **Experience** package (`@logto/experience`) renders the customizable sign-in and sign-up flows presented to end-users. When authentication initiates, the Core redirects users to this SPA (port `5001`), which collects credentials and returns them to complete the OIDC flow.

Essential source locations:

- [`packages/experience/src/App.tsx`](https://github.com/logto-io/logto/blob/main/packages/experience/src/App.tsx) – Experience application entry point
- [`packages/experience/src/pages/SignIn.tsx`](https://github.com/logto-io/logto/blob/main/packages/experience/src/pages/SignIn.tsx) – Sign-in interface component
- [`packages/experience/package.json`](https://github.com/logto-io/logto/blob/main/packages/experience/package.json) – Build tooling and dependencies

## Connector Ecosystem

**Connectors** provide pluggable integration with external identity providers and notification services. Each connector resides in a dedicated package under `packages/connectors/`, implementing a standard interface defined in `@logto/toolkit/connector-kit`.

Connector types include:

- **Social connectors** (GitHub, Google, Apple) for OAuth 2.0/SAML authentication
- **SMS connectors** for phone verification
- **Email connectors** for SMTP or API-based email delivery

The Core discovers connector packages at runtime and loads them as plugins. For example, `connector-github` handles the OAuth 2.0 handshake when tenants enable "Login with GitHub."

Implementation from [`packages/connectors/connector-github/src/index.ts`](https://github.com/logto-io/logto/blob/main/packages/connectors/connector-github/src/index.ts):

```typescript
import { createConnector } from '@logto/connector-kit';
import { fetch } from 'node-fetch';

export const githubConnector = createConnector({
  name: 'GitHub',
  type: 'social',
  async getAuthorizationUrl() {
    const redirectUri = `${process.env.BASE_URL}/callback/github`;
    return `https://github.com/login/oauth/authorize?client_id=${process.env.GITHUB_CLIENT_ID}&redirect_uri=${encodeURIComponent(redirectUri)}`;
  },
  async getUserInfo(code: string) {
    // Exchange code for token and fetch user profile
    const tokenRes = await fetch('https://github.com/login/oauth/access_token', {
      method: 'POST',
      body: new URLSearchParams({
        client_id: process.env.GITHUB_CLIENT_ID,
        client_secret: process.env.GITHUB_CLIENT_SECRET,
        code,
      }),
    });
    const token = await tokenRes.text();
    const profileRes = await fetch('https://api.github.com/user', {
      headers: { Authorization: `token ${token}` },
    });
    return await profileRes.json();
  },
});

```

Additional connector files:

- [`packages/connectors/connector-github/package.json`](https://github.com/logto-io/logto/blob/main/packages/connectors/connector-github/package.json) – GitHub connector manifest
- [`packages/connectors/connector-smtp/package.json`](https://github.com/logto-io/logto/blob/main/packages/connectors/connector-smtp/package.json) – SMTP email connector configuration

## Shared Toolkit and API Specifications

The **toolkit** packages (`@logto/toolkit/*`) contain reusable libraries consumed by multiple workspaces. These utilities provide password hashing algorithms, JWT handling, internationalization (i18n) support, and database abstraction layers.

Key toolkit components:

- [`packages/toolkit/core-kit/src/index.ts`](https://github.com/logto-io/logto/blob/main/packages/toolkit/core-kit/src/index.ts) – Core utilities and helpers
- [`packages/toolkit/core-kit/package.json`](https://github.com/logto-io/logto/blob/main/packages/toolkit/core-kit/package.json) – Toolkit configuration

The `@logto/api` package exports the **OpenAPI** (Swagger) specification that documents the Core's management and authentication endpoints. This specification, located at [`packages/api/openapi.yaml`](https://github.com/logto-io/logto/blob/main/packages/api/openapi.yaml), generates client SDKs for various programming languages.

## CLI and Development Tools

The **CLI** (`@logto/cli`) assists developers with project scaffolding, database seeding, and migration execution. It enables initialization of new Logto instances through `npm init @logto` and manages database alterations across environments.

CLI entry point: [`packages/cli/package.json`](https://github.com/logto-io/logto/blob/main/packages/cli/package.json)

**Demo applications** (`@logto/demo-app`) illustrate integration patterns for web and mobile clients. These examples demonstrate SDK usage for signing in, obtaining tokens, and calling protected resources, with the main entry at [`packages/demo-app/src/main.ts`](https://github.com/logto-io/logto/blob/main/packages/demo-app/src/main.ts).

## Runtime Architecture and Request Flow

Understanding how these components interact reveals the complete architectural overview of Logto:

1. **Development startup** – Running `pnpm dev` initializes the Core service on ports `3001` and `3002`, connects to PostgreSQL via `DB_URL`, and registers the OIDC provider.

2. **Administration flow** – Administrators access the Console SPA (port `5002`), which authenticates against the Core's management API to create tenants and configure policies.

3. **End-user authentication** – Client applications redirect users to the Core's `/experience` endpoint, which serves the Experience UI (port `5001`). The UI collects credentials and returns them to the Core to complete the OIDC token issuance.

4. **External integration** – When social login is configured, the Core delegates authentication to the appropriate connector package (e.g., `connector-github`), which handles the external OAuth 2.0 flow.

5. **Client integration** – Applications use Logto SDKs (generated from the OpenAPI spec) to interact with the Core endpoints, as shown in this client initialization from [`packages/sdk/js/src/client.ts`](https://github.com/logto-io/logto/blob/main/packages/sdk/js/src/client.ts):

```typescript
import { createLogtoClient } from '@logto/client';

// Initialise the SDK with the Core endpoint and your app ID
const logto = createLogtoClient({
  endpoint: 'http://localhost:3001',
  appId: 'your-app-id',
});

// Redirect the user to the sign‑in page
await logto.signIn();

// After the redirect back, fetch the access token
const accessToken = await logto.getAccessToken();

```

## Summary

- Logto organizes its identity platform as a **TypeScript monorepo** using npm workspaces to separate concerns while sharing build tooling.
- The **Core** (`@logto/core`) provides the OIDC/OAuth 2.1 implementation on Koa.js, exposing user and admin APIs on separate ports.
- **PostgreSQL** persistence is managed through the `@logto/schemas` package, which maintains migration files and TypeScript type definitions.
- Two **React/Vite** frontends serve distinct purposes: the **Admin Console** for management and the **Experience UI** for end-user authentication flows.
- **Connectors** enable pluggable integration with social providers and notification services, implementing a standard interface from the connector toolkit.
- **Shared toolkits** provide cross-cutting concerns like cryptography and i18n, while the **CLI** and **OpenAPI** specifications facilitate deployment and client generation.

## Frequently Asked Questions

### What backend framework does Logto use for its authentication server?

Logto implements its Core authentication service using **Koa.js**, a lightweight Node.js framework. The Core package (`@logto/core`) integrates the `oidc-provider` library to handle OIDC/OAuth 2.1 flows, with entry point logic defined in [`packages/core/src/index.ts`](https://github.com/logto-io/logto/blob/main/packages/core/src/index.ts) and routing configured in [`packages/core/src/routes.ts`](https://github.com/logto-io/logto/blob/main/packages/core/src/routes.ts).

### How does Logto manage database schema changes across versions?

Database migrations are maintained in the `@logto/schemas` package, specifically within the `packages/schemas/src/alterations/` directory. Initial schemas are defined in files like [`001_initial.sql`](https://github.com/logto-io/logto/blob/main/001_initial.sql), while TypeScript type definitions in [`packages/schemas/src/foundations/types.ts`](https://github.com/logto-io/logto/blob/main/packages/schemas/src/foundations/types.ts) ensure compile-time safety. The CLI (`@logto/cli`) executes these migrations during deployment.

### What distinguishes the Admin Console from the Experience UI in Logto's architecture?

The **Admin Console** (`@logto/console`) is an internal management interface running on port `5002` that configures tenants, applications, and policies via the Core's management API. The **Experience UI** (`@logto/experience`) runs on port `5001` and presents customizable sign-in/sign-up flows to end-users, communicating with the Core's OIDC endpoints to complete authentication sequences.

### How are external identity providers integrated into Logto?

External providers are integrated through **connectors**, which are separate packages following the `@logto/connector-<name>` naming convention. Each connector implements an interface from `@logto/toolkit/connector-kit` and resides in `packages/connectors/`. The Core discovers these packages at runtime, allowing tenants to enable social login (like GitHub in [`packages/connectors/connector-github/src/index.ts`](https://github.com/logto-io/logto/blob/main/packages/connectors/connector-github/src/index.ts)) without modifying the Core codebase.