# Understanding the Core Components of the Logto Architecture

> Explore the core components of the Logto architecture, an open-source identity platform. Discover its OIDC/OAuth 2.1 compliance, multi-tenancy, and pluggable connectors.

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

---

**Logto is built as a monorepo of tightly-coupled, independently versioned packages that together deliver a complete open-source identity platform implementing OIDC/OAuth 2.1, multi-tenancy, and pluggable authentication connectors.**

The logto-io/logto repository organizes its codebase into eight primary architectural pillars managed through a pnpm workspace. These components range from backend services handling identity protocols to frontend interfaces for administrators and end users, all orchestrated to provide a production-ready identity solution that can be self-hosted or deployed as Logto Cloud.

## Monorepo Foundation and Shared Utilities

Logto uses a **pnpm workspace** configuration defined in [`pnpm-workspace.yaml`](https://github.com/logto-io/logto/blob/main/pnpm-workspace.yaml) to manage dependencies across packages. This structure enables independent versioning and publishing while maintaining internal consistency.

The foundation rests on **schemas** (`packages/schemas/`) and **shared utilities** (`packages/shared/src/utils/`), which provide TypeScript definitions, validation helpers, and common logic for token generation and password hashing. These shared components ensure type safety across the backend services and frontend applications.

## Core Service: The Identity Backend

The **Core service** (`packages/core/`) functions as the central backend implementing OIDC/OAuth 2.1, SAML, multi-tenancy, RBAC, and the Management API. This Node.js application exposes two primary ports: **3001** for user-facing authentication flows and **3002** for administrative Management API access.

Key implementation files include:
- [`packages/core/src/index.ts`](https://github.com/logto-io/logto/blob/main/packages/core/src/index.ts) - Entry point that wires routing, database connections, and connector handling
- [`packages/core/src/routes/connector.ts`](https://github.com/logto-io/logto/blob/main/packages/core/src/routes/connector.ts) - Management API endpoints for connector configuration

The Core validates all payloads using shared schemas and delegates external identity provider calls to the connector ecosystem.

## Console: Administrative Interface

**Console** (`packages/console/`) is a Vite-powered React single-page application providing the administrative interface for managing tenants, applications, users, and connectors. Administrators use this UI to configure the entire Logto instance without direct API interaction.

The main application component resides in [`packages/console/src/App.tsx`](https://github.com/logto-io/logto/blob/main/packages/console/src/App.tsx), demonstrating consumption of the Management API on port 3002. Build configuration is handled in [`packages/console/vite.config.ts`](https://github.com/logto-io/logto/blob/main/packages/console/vite.config.ts).

## Experience: End-User Authentication UI

The **Experience** package (`packages/experience/`) renders the sign-in, sign-up, passwordless, and MFA interfaces that end users interact with. This Vite-based React application supports deep customization and can be embedded into existing applications.

Key files include:
- [`packages/experience/src/App.tsx`](https://github.com/logto-io/logto/blob/main/packages/experience/src/App.tsx) - Core routing and authentication flow logic
- [`packages/experience/vite.config.ts`](https://github.com/logto-io/logto/blob/main/packages/experience/vite.config.ts) - Build pipeline configuration

This component communicates with the Core's Experience API to handle complete authentication flows including social login redirects.

## Connector Ecosystem

**Connectors** are pluggable adapters living in `packages/connectors/` that enable Logto to communicate with external identity providers. Each connector resides in its own package (e.g., `packages/connectors/connector-google/`, `packages/connectors/connector-aliyun-sms-mas/`) and implements standardized interfaces for social login, SMS, email, and enterprise SSO.

These adapters act as thin translation layers that call third-party APIs and return standardized verification results to the Core service, allowing seamless integration with providers like Google, GitHub, or corporate SAML IdPs.

## Database and Schema Management

Logto persists all tenant, user, and configuration data in **PostgreSQL**. The `packages/schemas/` directory contains:
- Type definitions and Zod validation schemas
- Migration scripts in `packages/schemas/migrations/`
- Database alteration commands

Migrations are applied via the CLI using commands defined in [`packages/schemas/package.json`](https://github.com/logto-io/logto/blob/main/packages/schemas/package.json), ensuring all services share a compatible data model across deployments.

## Client SDKs

Logto provides **language-specific SDKs** in `packages/sdk/` that abstract HTTP calls and token handling for application developers. The JavaScript/TypeScript SDK (`packages/sdk/js/`) serves as the reference implementation, with additional support for Go (`packages/sdk/go/`) and Python.

The main façade is exported from [`packages/sdk/js/src/index.ts`](https://github.com/logto-io/logto/blob/main/packages/sdk/js/src/index.ts), providing methods like `createLogtoClient()` that handle OIDC flow implementation details including PKCE and refresh token rotation.

## CLI and DevOps Tooling

The **CLI** package (`packages/cli/`) provides essential commands for database seeding, running alterations, and managing development environments. Critical operations include:

- `pnpm cli alteration deploy` - Applies pending database migrations
- Database seeding for initial tenant and admin user creation

Implementation details are found in [`packages/cli/src/commands/alteration.ts`](https://github.com/logto-io/logto/blob/main/packages/cli/src/commands/alteration.ts) and related command directories.

## Architecture Flow and Integration

The Logto components interact through a specific request pipeline:

1. **Requests** hit the Core service on ports 3001 (user) or 3002 (admin)
2. The Core validates payloads using **schemas** and utilizes **shared utilities** for cryptography and token generation
3. For external identity provider integration, the Core delegates to the appropriate **connector** packages
4. **Administrators** configure the system via the **Console** UI, which calls the Management API
5. **End users** authenticate through the **Experience** UI, invoking the Core's Experience API
6. **Client applications** embed Logto via **SDKs** that handle token storage and refresh cycles
7. All persistent data is stored in **PostgreSQL**, with schema changes managed through the **CLI**

## Implementation Examples

### Initializing the Logto Client SDK

```typescript
import createLogtoClient from '@logto/js';

const logto = createLogtoClient({
  endpoint: 'https://your-logto-instance.com',
  appId: 'your-app-id',
});
await logto.signIn(); // redirects to the Experience UI

```

*Source: [`packages/sdk/js/src/index.ts`](https://github.com/logto-io/logto/blob/main/packages/sdk/js/src/index.ts)*

### Configuring Connectors via Management API

```typescript
import axios from 'axios';

await axios.post(
  'https://localhost:3002/api/v2/connectors',
  {
    type: 'social',
    connectorId: 'google',
    config: { clientId: 'xxx', clientSecret: 'yyy' },
  },
  { headers: { Authorization: `Bearer ${adminAccessToken}` } }
);

```

*Source: [`packages/core/src/routes/connector.ts`](https://github.com/logto-io/logto/blob/main/packages/core/src/routes/connector.ts)*

### Running Database Migrations

```bash
pnpm cli alteration deploy

```

*Source: [`packages/cli/src/commands/alteration.ts`](https://github.com/logto-io/logto/blob/main/packages/cli/src/commands/alteration.ts)*

### Customizing the Sign-In Component

```tsx
import { SignIn } from '@logto/experience';

function MySignIn() {
  return <SignIn
    signInUrl="https://your-logto-instance.com"
    socialConnectors={['google', 'github']}
  />;
}

```

*Source: [`packages/experience/src/components/SignIn.tsx`](https://github.com/logto-io/logto/blob/main/packages/experience/src/components/SignIn.tsx)*

## Summary

- **Core service** (`packages/core/`) implements OIDC/OAuth 2.1, SAML, and the Management API on ports 3001 and 3002
- **Console** (`packages/console/`) provides the Vite-based React admin interface for tenant and connector management
- **Experience** (`packages/experience/`) delivers the customizable end-user authentication UI supporting MFA and passwordless flows
- **Connectors** (`packages/connectors/`) supply pluggable adapters for social, SMS, email, and enterprise SSO integrations
- **Schemas** (`packages/schemas/`) define shared TypeScript types and PostgreSQL migration scripts for data consistency
- **SDKs** (`packages/sdk/`) offer language-specific client libraries for JavaScript/TypeScript, Go, and Python
- **CLI** (`packages/cli/`) handles database alterations, seeding, and development workflow management

## Frequently Asked Questions

### What database does Logto use and how are migrations managed?

Logto uses **PostgreSQL** as its primary data store for tenant, user, and configuration data. Database schema evolution is managed through migration scripts located in `packages/schemas/migrations/`, which are applied using the CLI command `pnpm cli alteration deploy` as implemented in [`packages/cli/src/commands/alteration.ts`](https://github.com/logto-io/logto/blob/main/packages/cli/src/commands/alteration.ts).

### Can the sign-in and admin interfaces be customized?

Yes, both interfaces are customizable React applications built with Vite. The **Experience** UI (`packages/experience/`) handles end-user authentication flows and supports theming and embedding, while the **Console** (`packages/console/`) provides the administrative interface. Both can be modified before building the monorepo, with entry points at [`packages/experience/src/App.tsx`](https://github.com/logto-io/logto/blob/main/packages/experience/src/App.tsx) and [`packages/console/src/App.tsx`](https://github.com/logto-io/logto/blob/main/packages/console/src/App.tsx) respectively.

### How does Logto integrate with external identity providers like Google or GitHub?

Logto integrates with external IdPs through the **connector** architecture. Each connector lives as an independent package in `packages/connectors/` (e.g., `connector-google`, `connector-github`) and implements a standardized interface defined in the Core service. The Core delegates authentication requests to these connectors, which handle the OAuth/SAML flows with third parties and return standardized verification results.

### What is the difference between Logto Core ports 3001 and 3002?

Port **3001** serves the **user-facing API** that handles end-user authentication flows, Experience API calls, and OIDC endpoints. Port **3002** exposes the **Management API** used by the Console and administrative operations for tenant configuration, user management, and connector setup. This separation enforces appropriate access control between end-user and administrative operations.