Manus Core Framework

Relevant source files

The following files were used as context for generating this wiki page:

• lib/_core/manus-runtime.ts
• lib/_core/api.ts
• server/_core/sdk.ts
• server/_core/oauth.ts
• server/_core/llm.ts
• drizzle/schema.ts
• server/storage.ts

The Manus Core Framework provides the foundational modules for backend communication, authentication, and core service integration within the aidoit4u-mobile-app. It consists of both client-side (lib/_core) and server-side (server/_core) components that work together. The framework is responsible for handling user authentication via Manus OAuth, managing API sessions, interacting with Large Language Models (LLMs) through the Forge API, and communicating with a parent container when the web app is embedded in an iframe.

This framework abstracts away the complexities of service integration, offering a consistent interface for the application to consume. It handles different authentication strategies for web (cookie-based) and native mobile (Bearer token) platforms, provides a runtime for web previews, and includes SDKs for interacting with core Manus services.

Authentication and User Management

The framework implements a complete authentication flow using Manus OAuth. It handles user creation, session management, and authentication for API requests. The core user data is stored in a users table.

Sources: server/_core/oauth.ts, server/_core/sdk.ts, drizzle/schema.ts, lib/_core/api.ts

User Data Model

The users table is the central entity for user information. It stores the unique Manus openId, user profile details, and session information.

This diagram shows the schema for the users table.

The table schema is defined in drizzle/schema.ts.

Field	Type	Constraints	Description
id	int	autoincrement, primaryKey	Surrogate primary key for relations.
openId	varchar(64)	notNull, unique	Manus OAuth identifier.
name	text		User's name.
email	varchar(320)		User's email.
loginMethod	varchar(64)		The method used for login (e.g., 'google').
role	enum('user', 'admin')	default('user'), notNull	User role within the application.
createdAt	timestamp	defaultNow(), notNull	Timestamp of user creation.
updatedAt	timestamp	defaultNow(), onUpdateNow(), notNull	Timestamp of the last update.
lastSignedIn	timestamp	defaultNow(), notNull	Timestamp of the last sign-in.
Sources: drizzle/schema.ts:12-20

OAuth Flow

The authentication process differs slightly between web and mobile clients. The server provides two distinct callback endpoints to handle this.

Web OAuth Flow

The web flow is a standard redirect-based OAuth flow. After successful authentication, the server sets a session cookie and redirects the user back to the frontend application.

This sequence diagram illustrates the web authentication flow.

Mobile OAuth Flow

The mobile flow is designed for native clients. Instead of a redirect, the /api/oauth/mobile endpoint returns a JSON payload containing the app_session_id (session token) and user details, which the client is responsible for storing securely.

This sequence diagram illustrates the mobile authentication flow.

API Endpoints

The framework exposes several endpoints for authentication.

Endpoint	Method	Description
/api/oauth/callback	GET	Handles the web OAuth redirect, sets a session cookie, and redirects to the frontend.
/api/oauth/mobile	GET	Handles the mobile OAuth code exchange, returning a session token and user data as JSON.
/api/auth/logout	POST	Clears the session cookie.
/api/auth/me	GET	Returns the currently authenticated user, works with both cookie and Bearer token.
/api/auth/session	POST	Establishes a session cookie from a provided Bearer token. Used for the iframe preview.
Sources: server/_core/oauth.ts

API Communication (lib/_core/api.ts)

The apiCall function is a generic wrapper for making fetch requests to the backend. It automatically handles authentication based on the platform.

Sources: lib/_core/api.ts:8-108

This flowchart shows the logic within the apiCall function.

Key features of apiCall:

• Platform-Aware Auth: On native platforms (iOS/Android), it retrieves a session token from secure storage and adds it as a Bearer token to the Authorization header. On the web, it relies on the browser to automatically send the session cookie by setting credentials: "include".
• URL Construction: It combines the base API URL with the endpoint, ensuring no double slashes.
• Error Handling: It checks for non-OK responses and throws an error with the response body.
• JSON Parsing: It automatically parses JSON responses.

Manus Runtime (Web Iframe Communication)

The Manus Runtime is a client-side module that facilitates communication between the Expo web application and its parent container (e.g., the Manus platform's previewer) when it's running inside an <iframe>. It uses the window.postMessage API.

Sources: lib/_core/manus-runtime.ts

Initialization and Handshake

When the app starts, initManusRuntime() is called. This function checks if the app is in an iframe and, if so, sends an appDevServerReady message to the parent window. This signals that the app has loaded and is ready to receive messages.

This sequence diagram shows the initialization process.

Safe Area Insets

The parent container can send setSafeAreaInsets messages to the app to provide safe area dimensions, which is crucial for mimicking a native device's screen layout (e.g., notches and home indicators) in a web preview. The app subscribes to these updates using subscribeSafeAreaInsets.

Sources: lib/_core/manus-runtime.ts:72-82, 90-97

LLM Service Integration

The framework provides a standardized way to interact with LLMs via the Forge API using the invokeLLM function. It handles request normalization, authentication, and response parsing.

Sources: server/_core/llm.ts

Invocation Flow

The invokeLLM function takes a set of parameters, constructs a payload compliant with the Forge Chat Completions API, and sends the request.

This flowchart outlines the steps taken by invokeLLM.

Key Data Structures

The invokeLLM function uses several specific types to structure the request.

Parameter	Type	Description
messages	Message[]	An array of message objects, each with a role and content.
tools	Tool[]	An optional array of functions the model can call.
toolChoice	ToolChoice	Controls how the model uses tools (e.g., 'auto', 'none', or a specific function).
outputSchema	JsonSchema	Defines a JSON schema for structured output.
responseFormat	ResponseFormat	Specifies the output format, such as json_object.
Sources: server/_core/llm.ts:55-71

Storage Service

The storage.ts module provides helpers (storagePut, storageGet) to interact with the Manus storage proxy. This is used for uploading and retrieving files.

Sources: server/storage.ts

• storagePut(relKey, data, contentType): Uploads data to the storage service. It constructs a FormData object and POSTs it to the /v1/storage/upload endpoint with bearer token authentication.
• storageGet(relKey): Retrieves a signed download URL for a file. It makes a GET request to /v1/storage/downloadUrl.

Both functions rely on BUILT_IN_FORGE_API_URL and BUILT_IN_FORGE_API_KEY environment variables for configuration.

Sources: server/storage.ts:9-16, 81-102, 104-111