Understanding the Core Components of the Logto Architecture

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 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 - Entry point that wires routing, database connections, and connector handling
• 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, demonstrating consumption of the Management API on port 3002. Build configuration is handled in 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 - Core routing and authentication flow logic
• 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, 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, 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 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

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

Configuring Connectors via Management API

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

Running Database Migrations

pnpm cli alteration deploy

Source: packages/cli/src/commands/alteration.ts

Customizing the Sign-In Component

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

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.

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 and 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}