Deploy Taqarub Node API server

Dockerfile

@@ -0,0 +1,29 @@
+FROM node:20-alpine
+
+RUN corepack enable && corepack prepare pnpm@9.12.0 --activate
+
+WORKDIR /app
+
+COPY package.json pnpm-lock.yaml ./
+RUN pnpm install --frozen-lockfile
+
+COPY server/ server/
+COPY shared/ shared/
+COPY drizzle/ drizzle/
+COPY drizzle.config.ts tsconfig.json ./
+
+RUN npx esbuild server/_core/index.ts \
+    --platform=node \
+    --packages=external \
+    --bundle \
+    --format=cjs \
+    --outdir=dist
+
+RUN pnpm prune --prod
+
+ENV NODE_ENV=production
+ENV PORT=7860
+
+EXPOSE 7860
+
+CMD ["node", "dist/index.js"]

README.md

@@ -0,0 +1,10 @@
+---
+title: Taqarub Node API
+emoji: 🚀
+colorFrom: green
+colorTo: blue
+sdk: docker
+pinned: false
+---
+
+# Taqarub Node API Server

drizzle.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from "drizzle-kit";
+
+const connectionString = process.env.DATABASE_URL;
+if (!connectionString) {
+  throw new Error("DATABASE_URL is required to run drizzle commands");
+}
+
+export default defineConfig({
+  schema: "./drizzle/schema.ts",
+  out: "./drizzle",
+  dialect: "mysql",
+  dbCredentials: {
+    url: connectionString,
+  },
+});

drizzle/0000_elite_eternals.sql

@@ -0,0 +1,13 @@
+CREATE TABLE `users` (
+	`id` int AUTO_INCREMENT NOT NULL,
+	`openId` varchar(64) NOT NULL,
+	`name` text,
+	`email` varchar(320),
+	`loginMethod` varchar(64),
+	`role` enum('user','admin') NOT NULL DEFAULT 'user',
+	`createdAt` timestamp NOT NULL DEFAULT (now()),
+	`updatedAt` timestamp NOT NULL DEFAULT (now()) ON UPDATE CURRENT_TIMESTAMP,
+	`lastSignedIn` timestamp NOT NULL DEFAULT (now()),
+	CONSTRAINT `users_id` PRIMARY KEY(`id`),
+	CONSTRAINT `users_openId_unique` UNIQUE(`openId`)
+);

drizzle/meta/0000_snapshot.json

@@ -0,0 +1,106 @@
+{
+  "version": "5",
+  "dialect": "mysql",
+  "id": "3c3a03ea-b871-416a-b531-aa772cca8b00",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "tables": {
+    "users": {
+      "name": "users",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "int",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "openId": {
+          "name": "openId",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "email": {
+          "name": "email",
+          "type": "varchar(320)",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "loginMethod": {
+          "name": "loginMethod",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "role": {
+          "name": "role",
+          "type": "enum('user','admin')",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'user'"
+        },
+        "createdAt": {
+          "name": "createdAt",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(now())"
+        },
+        "updatedAt": {
+          "name": "updatedAt",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "onUpdate": true,
+          "default": "(now())"
+        },
+        "lastSignedIn": {
+          "name": "lastSignedIn",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(now())"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {
+        "users_id": {
+          "name": "users_id",
+          "columns": ["id"]
+        }
+      },
+      "uniqueConstraints": {
+        "users_openId_unique": {
+          "name": "users_openId_unique",
+          "columns": ["openId"]
+        }
+      },
+      "checkConstraint": {}
+    }
+  },
+  "views": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "tables": {},
+    "indexes": {}
+  }
+}

drizzle/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "mysql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "5",
+      "when": 1763372440610,
+      "tag": "0000_elite_eternals",
+      "breakpoints": true
+    }
+  ]
+}

drizzle/relations.ts

@@ -0,0 +1 @@
+import {} from "./schema";

drizzle/schema.ts

@@ -0,0 +1,28 @@
+import { int, mysqlEnum, mysqlTable, text, timestamp, varchar } from "drizzle-orm/mysql-core";
+
+/**
+ * Core user table backing auth flow.
+ * Extend this file with additional tables as your product grows.
+ * Columns use camelCase to match both database fields and generated types.
+ */
+export const users = mysqlTable("users", {
+  /**
+   * Surrogate primary key. Auto-incremented numeric value managed by the database.
+   * Use this for relations between tables.
+   */
+  id: int("id").autoincrement().primaryKey(),
+  /** Manus OAuth identifier (openId) returned from the OAuth callback. Unique per user. */
+  openId: varchar("openId", { length: 64 }).notNull().unique(),
+  name: text("name"),
+  email: varchar("email", { length: 320 }),
+  loginMethod: varchar("loginMethod", { length: 64 }),
+  role: mysqlEnum("role", ["user", "admin"]).default("user").notNull(),
+  createdAt: timestamp("createdAt").defaultNow().notNull(),
+  updatedAt: timestamp("updatedAt").defaultNow().onUpdateNow().notNull(),
+  lastSignedIn: timestamp("lastSignedIn").defaultNow().notNull(),
+});
+
+export type User = typeof users.$inferSelect;
+export type InsertUser = typeof users.$inferInsert;
+
+// TODO: Add your tables here

package.json

@@ -0,0 +1,108 @@
+{
+  "name": "app-template",
+  "version": "1.0.0",
+  "private": true,
+  "main": "expo-router/entry",
+  "scripts": {
+    "dev": "concurrently -k \"pnpm dev:server\" \"pnpm dev:metro\"",
+    "dev:server": "cross-env NODE_ENV=development tsx watch server/_core/index.ts",
+    "dev:metro": "cross-env EXPO_USE_METRO_WORKSPACE_ROOT=1 npx expo start --web --port 8081",
+    "build": "esbuild server/_core/index.ts --platform=node --packages=external --bundle --format=esm --outdir=dist",
+    "start": "cross-env NODE_ENV=production node dist/index.js",
+    "check": "tsc --noEmit",
+    "lint": "expo lint",
+    "format": "prettier --write .",
+    "test": "vitest run",
+    "db:push": "drizzle-kit generate && drizzle-kit migrate",
+    "android": "expo run:android",
+    "ios": "expo run:ios",
+    "qr": "node scripts/generate_qr.mjs"
+  },
+  "dependencies": {
+    "@expo/vector-icons": "^15.0.3",
+    "@react-native-async-storage/async-storage": "^2.2.0",
+    "@react-navigation/bottom-tabs": "^7.8.12",
+    "@react-navigation/elements": "^2.9.2",
+    "@react-navigation/native": "^7.1.25",
+    "@tanstack/react-query": "^5.90.12",
+    "@trpc/client": "11.7.2",
+    "@trpc/react-query": "11.7.2",
+    "@trpc/server": "11.7.2",
+    "@types/three": "^0.183.1",
+    "@types/ws": "^8.18.1",
+    "axios": "^1.13.2",
+    "clsx": "^2.1.1",
+    "cookie": "^1.1.1",
+    "dotenv": "^16.6.1",
+    "drizzle-orm": "^0.44.7",
+    "expo": "~54.0.29",
+    "expo-asset": "~12.0.12",
+    "expo-audio": "~1.1.0",
+    "expo-build-properties": "^1.0.10",
+    "expo-camera": "~17.0.10",
+    "expo-clipboard": "~8.0.8",
+    "expo-constants": "~18.0.12",
+    "expo-dev-client": "~6.0.20",
+    "expo-file-system": "~19.0.21",
+    "expo-font": "~14.0.10",
+    "expo-gl": "~16.0.10",
+    "expo-haptics": "~15.0.8",
+    "expo-image": "~3.0.11",
+    "expo-keep-awake": "~15.0.8",
+    "expo-linking": "~8.0.10",
+    "expo-modules-core": "~3.0.29",
+    "expo-notifications": "~0.32.15",
+    "expo-router": "~6.0.19",
+    "expo-secure-store": "~15.0.8",
+    "expo-speech": "~14.0.8",
+    "expo-speech-recognition": "^3.1.2",
+    "expo-splash-screen": "~31.0.12",
+    "expo-status-bar": "~3.0.9",
+    "expo-symbols": "~1.0.8",
+    "expo-system-ui": "~6.0.9",
+    "expo-video": "~3.0.15",
+    "expo-web-browser": "~15.0.10",
+    "express": "^4.22.1",
+    "jose": "6.1.0",
+    "mediapipe": "^0.0.1-security",
+    "mysql2": "^3.16.0",
+    "nativewind": "^4.2.1",
+    "react": "19.1.0",
+    "react-dom": "19.1.0",
+    "react-native": "0.81.5",
+    "react-native-gesture-handler": "~2.28.0",
+    "react-native-reanimated": "~4.1.6",
+    "react-native-safe-area-context": "~5.6.2",
+    "react-native-screens": "~4.16.0",
+    "react-native-svg": "15.12.1",
+    "react-native-web": "~0.21.2",
+    "react-native-worklets": "0.5.1",
+    "superjson": "^1.13.3",
+    "tailwind-merge": "^2.6.0",
+    "three": "^0.183.2",
+    "ws": "^8.19.0",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@expo/ngrok": "^4.1.3",
+    "@types/cookie": "^0.6.0",
+    "@types/express": "^4.17.25",
+    "@types/node": "^22.19.3",
+    "@types/qrcode": "^1.5.6",
+    "@types/react": "~19.1.17",
+    "concurrently": "^9.2.1",
+    "cross-env": "^7.0.3",
+    "drizzle-kit": "^0.31.8",
+    "esbuild": "^0.25.12",
+    "eslint": "^9.39.2",
+    "eslint-config-expo": "~10.0.0",
+    "prettier": "^3.7.4",
+    "qrcode": "^1.5.4",
+    "tailwindcss": "^3.4.17",
+    "tsx": "^4.21.0",
+    "typescript": "~5.9.3",
+    "vitest": "^2.1.9",
+    "yaml": "^2.8.2"
+  },
+  "packageManager": "pnpm@9.12.0"
+}

server/README.md

@@ -0,0 +1,1235 @@
+# Backend Development Guide
+
+This guide covers server-side features including authentication, database, tRPC API, and integrations. **Only read this if your app needs these capabilities.**
+
+---
+
+## When Do You Need Backend?
+
+| Scenario | Backend Needed? | User Auth Required? | Solution |
+|----------|-----------------|---------------------|----------|
+| Data stays on device only | No | No | Use `AsyncStorage` |
+| Data syncs across devices | Yes | Yes | Database + tRPC |
+| User accounts / login | Yes | Yes | Manus OAuth |
+| AI-powered features | Yes | **Optional** | LLM Integration |
+| User uploads files | Yes | **Optional** | S3 Storage |
+| Server-side validation | Yes | **Optional** | tRPC procedures |
+
+> **Note:** Backend ≠ User Auth. You can run a backend with LLM/Storage/ImageGen capabilities without requiring user login — just use `publicProcedure` instead of `protectedProcedure`. User auth is only mandatory when you need to identify users or sync user-specific data.
+
+---
+
+## File Structure
+
+```
+server/
+  db.ts              ← Query helpers (add database functions here)
+  routers.ts         ← tRPC procedures (add API routes here)
+  storage.ts         ← S3 storage helpers (can extend)
+  _core/             ← Framework-level code (don't modify)
+drizzle/
+  schema.ts          ← Database tables & types (add your tables here)
+  relations.ts       ← Table relationships
+  migrations/        ← Auto-generated migrations
+shared/
+  types.ts           ← Shared TypeScript types
+  const.ts           ← Shared constants
+  _core/             ← Framework-level code (don't modify)
+lib/
+  trpc.ts            ← tRPC client (can customize headers)
+  _core/             ← Framework-level code (don't modify)
+hooks/
+  use-auth.ts        ← Auth state hook (don't modify)
+tests/
+  *.test.ts          ← Add your tests here
+```
+
+Only touch the files with "←" markers. Anything under `_core/` directories is framework-level—avoid editing unless you are extending the infrastructure.
+
+---
+
+## Authentication
+
+### Overview
+
+The template uses **Manus OAuth** for user authentication. It works differently on native and web:
+
+| Platform | Auth Method | Token Storage |
+|----------|-------------|---------------|
+| iOS/Android | Bearer token | expo-secure-store |
+| Web | HTTP-only cookie | Browser cookie |
+
+### Using the Auth Hook
+
+```tsx
+import { useAuth } from "@/hooks/use-auth";
+
+function MyScreen() {
+  const { user, isAuthenticated, loading, logout } = useAuth();
+
+  if (loading) return <ActivityIndicator />;
+  
+  if (!isAuthenticated) {
+    return <LoginButton />;
+  }
+
+  return (
+    <View>
+      <ThemedText>Welcome, {user.name}</ThemedText>
+      <Button title="Logout" onPress={logout} />
+    </View>
+  );
+}
+```
+
+### User Object
+
+The `user` object contains:
+
+```tsx
+interface User {
+  id: number;
+  openId: string;        // Manus OAuth ID
+  name: string | null;
+  email: string | null;
+  loginMethod: string;
+  role: "user" | "admin";
+  lastSignedIn: Date;
+}
+```
+
+### Login Flow (Native)
+
+1. User taps Login button
+2. `startOAuthLogin()` calls `Linking.openURL()` which opens Manus OAuth in the system browser
+3. User authenticates
+4. OAuth redirects to the app's deep link (`/oauth/callback`) with code/state params
+5. App opens the callback handler
+6. Callback exchanges code for session token
+7. Token stored in SecureStore
+8. User redirected to home
+
+### Login Flow (Web)
+
+1. User clicks Login button
+2. Browser redirects to Manus OAuth
+3. User authenticates
+4. Redirect back with session cookie
+5. Cookie automatically sent with requests
+
+### Protected Routes
+
+Use `protectedProcedure` in tRPC to require authentication:
+
+```tsx
+// server/routers.ts
+import { protectedProcedure } from "./_core/trpc";
+
+export const appRouter = router({
+  myFeature: router({
+    getData: protectedProcedure.query(({ ctx }) => {
+      // ctx.user is guaranteed to exist
+      return db.getUserData(ctx.user.id);
+    }),
+  }),
+});
+
+```
+### Frontend: Handling Auth Errors
+protectedProcedure MUST HANDLE UNAUTHORIZED when user is not logged in. Always handle this in the frontend:
+```tsx
+try {
+  await trpc.someProtectedEndpoint.mutate(data);
+} catch (error) {
+  if (error.data?.code === 'UNAUTHORIZED') {
+    router.push('/login');
+    return;
+  }
+  throw error;
+}
+```
+
+---
+
+## Database
+
+### Schema Definition
+
+Define your tables in `drizzle/schema.ts`:
+
+```tsx
+import { int, mysqlTable, text, timestamp, varchar } from "drizzle-orm/mysql-core";
+
+// Users table (already exists)
+export const users = mysqlTable("users", {
+  id: int("id").autoincrement().primaryKey(),
+  openId: varchar("openId", { length: 64 }).notNull().unique(),
+  name: text("name"),
+  email: varchar("email", { length: 320 }),
+  role: mysqlEnum("role", ["user", "admin"]).default("user").notNull(),
+  createdAt: timestamp("createdAt").defaultNow().notNull(),
+  updatedAt: timestamp("updatedAt").defaultNow().onUpdateNow().notNull(),
+});
+
+// Add your tables
+export const items = mysqlTable("items", {
+  id: int("id").autoincrement().primaryKey(),
+  userId: int("userId").notNull(),
+  title: varchar("title", { length: 255 }).notNull(),
+  description: text("description"),
+  completed: boolean("completed").default(false).notNull(),
+  createdAt: timestamp("createdAt").defaultNow().notNull(),
+});
+
+// Export types
+export type User = typeof users.$inferSelect;
+export type Item = typeof items.$inferSelect;
+export type InsertItem = typeof items.$inferInsert;
+```
+
+### Running Migrations
+
+After editing the schema, push changes to the database:
+
+```bash
+pnpm db:push
+```
+
+This runs `drizzle-kit generate` and `drizzle-kit migrate`.
+
+### Query Helpers
+
+Add database queries in `server/db.ts`:
+
+```tsx
+import { eq } from "drizzle-orm";
+import { getDb } from "./_core/db";
+import { items, InsertItem } from "../drizzle/schema";
+
+export async function getUserItems(userId: number) {
+  const db = await getDb();
+  if (!db) return [];
+  
+  return db.select().from(items).where(eq(items.userId, userId));
+}
+
+export async function createItem(data: InsertItem) {
+  const db = await getDb();
+  if (!db) throw new Error("Database not available");
+  
+  const result = await db.insert(items).values(data);
+  return result.insertId;
+}
+
+export async function updateItem(id: number, data: Partial<InsertItem>) {
+  const db = await getDb();
+  if (!db) throw new Error("Database not available");
+  
+  await db.update(items).set(data).where(eq(items.id, id));
+}
+
+export async function deleteItem(id: number) {
+  const db = await getDb();
+  if (!db) throw new Error("Database not available");
+  
+  await db.delete(items).where(eq(items.id, id));
+}
+```
+
+---
+
+## tRPC API
+
+### Adding Routes
+
+Define API routes in `server/routers.ts`:
+
+```tsx
+import { z } from "zod";
+import { router, protectedProcedure, publicProcedure } from "./_core/trpc";
+import * as db from "./db";
+
+export const appRouter = router({
+  // Public route (no auth required)
+  health: publicProcedure.query(() => ({ status: "ok" })),
+
+  // Protected routes (auth required)
+  items: router({
+    list: protectedProcedure.query(({ ctx }) => {
+      return db.getUserItems(ctx.user.id);
+    }),
+
+    create: protectedProcedure
+      .input(z.object({
+        title: z.string().min(1).max(255),
+        description: z.string().optional(),
+      }))
+      .mutation(({ ctx, input }) => {
+        return db.createItem({
+          userId: ctx.user.id,
+          title: input.title,
+          description: input.description,
+        });
+      }),
+
+    update: protectedProcedure
+      .input(z.object({
+        id: z.number(),
+        title: z.string().min(1).max(255).optional(),
+        completed: z.boolean().optional(),
+      }))
+      .mutation(({ input }) => {
+        return db.updateItem(input.id, input);
+      }),
+
+    delete: protectedProcedure
+      .input(z.object({ id: z.number() }))
+      .mutation(({ input }) => {
+        return db.deleteItem(input.id);
+      }),
+  }),
+});
+
+export type AppRouter = typeof appRouter;
+```
+
+### Calling from Frontend
+
+Use tRPC hooks in your components:
+
+```tsx
+import { trpc } from "@/lib/trpc";
+
+function ItemList() {
+  // Query
+  const { data: items, isLoading, refetch } = trpc.items.list.useQuery();
+
+  // Mutation
+  const createMutation = trpc.items.create.useMutation({
+    onSuccess: () => refetch(),
+  });
+
+  const handleCreate = async () => {
+    await createMutation.mutateAsync({
+      title: "New Item",
+      description: "Description here",
+    });
+  };
+
+  if (isLoading) return <ActivityIndicator />;
+
+  return (
+    <FlatList
+      data={items}
+      keyExtractor={(item) => item.id.toString()}
+      renderItem={({ item }) => <ItemCard item={item} />}
+    />
+  );
+}
+```
+
+### Input Validation
+
+Use Zod schemas for type-safe validation:
+
+```tsx
+import { z } from "zod";
+
+const createItemSchema = z.object({
+  title: z.string().min(1, "Title required").max(255),
+  description: z.string().max(1000).optional(),
+  priority: z.enum(["low", "medium", "high"]).default("medium"),
+  dueDate: z.date().optional(),
+});
+
+// In router
+create: protectedProcedure
+  .input(createItemSchema)
+  .mutation(({ ctx, input }) => {
+    // input is fully typed
+  }),
+```
+
+---
+
+## LLM Integration
+
+Use the preconfigured LLM helpers. Credentials are injected from the platform (no manual setup required).
+
+```ts
+import { invokeLLM } from "./server/_core/llm";
+
+/**
+ * Simple chat completion
+ * type Role = "system" | "user" | "assistant" | "tool" | "function";
+ * type TextContent = {
+ *   type: "text";
+ *   text: string;
+ * };
+ *
+ * type ImageContent = {
+ *   type: "image_url";
+ *   image_url: {
+ *     url: string;
+ *     detail?: "auto" | "low" | "high";
+ *   };
+ * };
+ *
+ * type FileContent = {
+ *   type: "file_url";
+ *   file_url: {
+ *     url: string;
+ *     mime_type?: "audio/mpeg" | "audio/wav" | "application/pdf" | "audio/mp4" | "video/mp4" ;
+ *   };
+ * };
+ *
+ * export type Message = {
+ *   role: Role;
+ *   content: string | Array<ImageContent | TextContent | FileContent>
+ * };
+ *
+ * Supported parameters:
+ * messages: Array<{
+ *   role: 'system' | 'user' | 'assistant' | 'tool',
+ *   content: string | { tool_call: { name: string, arguments: string } }
+ * }>
+ * tool_choice?: 'none' | 'auto' | 'required' | { type: 'function', function: { name: string } }
+ * tools?: Tool[]
+ */
+const response = await invokeLLM({
+  messages: [
+    { role: "system", content: "You are a helpful assistant." },
+    { role: "user", content: "Hello, world!" },
+  ],
+});
+```
+
+Tips
+- Always call llm functions from server-side code (e.g., inside tRPC procedures), to avoid exposing your API key.
+- You don't need to manually set the model; the helper uses a sensible default.
+- LLM responses often contain markdown. Use `<Streamdown>{content}</Streamdown>` (imported from `streamdown`) to render markdown content with proper formatting and streaming support.
+- For image-based gen AI workflows, local `file://` and blob URLs don't work. Upload to S3 first, then pass the public URL to `invokeLLM()`.
+
+### Structured Responses (JSON Schema)
+
+Ask the model to return structured JSON via `response_format`:
+
+```ts
+import { invokeLLM } from "./server/_core/llm";
+
+const structured = await invokeLLM({
+  messages: [
+    { role: "system", content: "You are a helpful assistant designed to output JSON." },
+    { role: "user", content: "Extract the name and age from the following text: \"My name is Alice and I am 30 years old.\"" },
+  ],
+  response_format: {
+    type: "json_schema",
+    json_schema: {
+      name: "person_info",
+      strict: true,
+      schema: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "The name of the person" },
+          age: { type: "integer", description: "The age of the person" },
+        },
+        required: ["name", "age"],
+        additionalProperties: false,
+      },
+    },
+  },
+});
+
+// The model responds with JSON content matching the schema.
+// Access via `structured.choices[0].message.content` and JSON.parse if needed.
+```
+The helpers mirror the Python SDK semantics but produce JavaScript-first code, keeping credentials inside the server and ensuring every environment has access to the same token.
+
+**CRITICAL Note:** `json_schema` works for flat structures. For nested arrays/objects, use `json_object` instead.
+```ts
+const response = await invokeLLM({
+  messages: [
+    {
+      role: "system",
+      content: `Analyze the food image. Return JSON:
+{
+  "foods": [{ "name": "string", "calories": number }],
+  "totalCalories": number
+}`
+    },
+    {
+      role: "user",
+      content: [
+        { type: "text", text: "What food is this?" },
+        { type: "image_url", image_url: { url: imageUrl } }
+      ]
+    }
+  ],
+  response_format: { type: "json_object" }
+});
+const data = JSON.parse(response.choices[0].message.content);
+```
+
+---
+
+## Voice Transcription Integration
+
+Use the preconfigured voice transcription helper that converts speech to text using Whisper API, no manual setup required.
+
+Example usage:
+```ts
+import { transcribeAudio } from "./server/_core/voiceTranscription";
+
+const result = await transcribeAudio({
+  audioUrl: "https://storage.example.com/audio/recording.mp3",
+  language: "en", // Optional: helps improve accuracy
+  prompt: "Transcribe meeting notes" // Optional: context hint
+});
+
+// Returns native Whisper API response
+// result.text - Full transcription
+// result.language - Detected language (ISO-639-1)
+// result.segments - Timestamped segments with metadata
+```
+
+Tips
+- Accepts URL to pre-uploaded audio file
+- 16MB file size limit enforced during transcription, size flag to be set by frontend
+- Supported formats: webm, mp3, wav, ogg, m4a
+- Returns native Whisper API response with rich metadata
+- Frontend should handle audio capture, storage upload, and size validation
+
+---
+
+## Image Generation Integration
+
+Use the preconfigured image generation helper that connects to the internal ImageService, no manual setup required.
+
+Example usage:
+```ts
+import { generateImage } from "./server/_core/imageGeneration.ts";
+
+const { url: imageUrl } = await generateImage({
+  prompt: "A serene landscape with mountains"
+});
+// For editing:
+const { url: imageUrl } = await generateImage({
+  prompt: "Add a rainbow to this landscape",
+  originalImages: [{
+    url: "https://example.com/original.jpg",
+    mimeType: "image/jpeg"
+  }]
+});
+```
+
+Tips
+- Always call from server-side code (e.g., inside tRPC procedures) to avoid exposing API keys
+- Image generation can take 5-20 seconds, implement proper loading states
+- Implement proper error handling as image generation can fail
+
+---
+
+## ☁️ File Storage
+
+Use the preconfigured S3 helpers in `server/storage.ts`. Credentials are injected from the platform (no manual setup required).
+
+```ts
+import { storagePut } from "./server/storage";
+
+// Upload bytes to S3 with non-enumerable path
+// The S3 bucket is public, so returned URLs work without additional signing process
+// Add random suffixes to file keys to prevent enumeration
+const fileKey = `${userId}-files/${fileName}-${randomSuffix()}.png`
+const { url } = await storagePut(
+  fileKey,
+  fileBuffer, // Buffer | Uint8Array | string
+  "image/png"
+);
+```
+
+Tips
+- Save metadata (path/URL/ACL/owner/mime/size) in your database; use S3 for the actual file bytes. This applies to all files including images, documents, and media.
+- For file uploads, have the client POST to your server, then call `storagePut` from your backend.
+
+---
+
+## ☁️ Data API
+
+When you need external data, use the omni_search with search_type = 'api' to see there's any built-in api available in Manus API Hub access. You only have to connect other api if there's no suitable built-in api available.
+
+---
+
+## Owner Notifications
+
+This template already ships with a `notifyOwner({ title, content })` helper (`server/_core/notification.ts`) and a protected tRPC mutation at `trpc.system.notifyOwner`. Use it whenever backend logic needs to push an operational update to the Manus project owner—common triggers are new form submissions, survey feedback, or workflow results.
+
+1. On the server, call `await notifyOwner({ title, content })` or reuse the provided `system.notifyOwner` mutation from jobs/webhooks (`trpc.system.notifyOwner.useMutation()` on the client).
+2. Handle the boolean return (`true` on success, `false` if the upstream service is temporarily unavailable) to decide whether you need a fallback channel.
+
+Keep this channel for owner-facing alerts; end-user messaging should flow through your app-specific systems.
+
+---
+
+## Environment Variables
+
+Available environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `DATABASE_URL` | MySQL/TiDB connection string |
+| `JWT_SECRET` | Session signing secret |
+| `VITE_APP_ID` | Manus OAuth app ID |
+| `OAUTH_SERVER_URL` | Manus OAuth backend URL |
+| `VITE_OAUTH_PORTAL_URL` | Manus login portal URL |
+| `OWNER_OPEN_ID` | Owner's Manus ID |
+| `OWNER_NAME` | Owner's display name |
+| `BUILT_IN_FORGE_API_URL` | Manus API endpoint |
+| `BUILT_IN_FORGE_API_KEY` | Manus API key |
+
+Expo runtime variables (prefixed with `EXPO_PUBLIC_`):
+
+| Variable | Description |
+|----------|-------------|
+| `EXPO_PUBLIC_APP_ID` | App ID for OAuth |
+| `EXPO_PUBLIC_API_BASE_URL` | API server URL |
+| `EXPO_PUBLIC_OAUTH_PORTAL_URL` | Login portal URL |
+
+---
+
+## Testing
+
+Write tests in `tests/` using Vitest:
+
+```tsx
+// tests/items.test.ts
+import { describe, expect, it } from "vitest";
+import { appRouter } from "../server/routers";
+
+describe("items", () => {
+  it("creates an item", async () => {
+    const ctx = createMockContext({ userId: 1 });
+    const caller = appRouter.createCaller(ctx);
+
+    const result = await caller.items.create({
+      title: "Test Item",
+      description: "Test description",
+    });
+
+    expect(result).toBeDefined();
+  });
+});
+```
+
+Run tests:
+
+```bash
+pnpm test
+```
+
+---
+
+## Key Files Reference
+
+## Core File References
+
+`drizzle/schema.ts`
+```ts
+import { int, mysqlEnum, mysqlTable, text, timestamp, varchar } from "drizzle-orm/mysql-core";
+
+/**
+ * Core user table backing auth flow.
+ * Extend this file with additional tables as your product grows.
+ * Columns use camelCase to match both database fields and generated types.
+ */
+export const users = mysqlTable("users", {
+  /**
+   * Surrogate primary key. Auto-incremented numeric value managed by the database.
+   * Use this for relations between tables.
+   */
+  id: int("id").autoincrement().primaryKey(),
+  /** Manus OAuth identifier (openId) returned from the OAuth callback. Unique per user. */
+  openId: varchar("openId", { length: 64 }).notNull().unique(),
+  name: text("name"),
+  email: varchar("email", { length: 320 }),
+  loginMethod: varchar("loginMethod", { length: 64 }),
+  role: mysqlEnum("role", ["user", "admin"]).default("user").notNull(),
+  createdAt: timestamp("createdAt").defaultNow().notNull(),
+  updatedAt: timestamp("updatedAt").defaultNow().onUpdateNow().notNull(),
+  lastSignedIn: timestamp("lastSignedIn").defaultNow().notNull(),
+});
+
+export type User = typeof users.$inferSelect;
+export type InsertUser = typeof users.$inferInsert;
+
+// TODO: Add your tables here
+```
+
+`server/db.ts`
+```ts
+import { eq } from "drizzle-orm";
+import { drizzle } from "drizzle-orm/mysql2";
+import { InsertUser, users } from "../drizzle/schema";
+import { ENV } from "./_core/env";
+
+let _db: ReturnType<typeof drizzle> | null = null;
+
+// Lazily create the drizzle instance so local tooling can run without a DB.
+export async function getDb() {
+  if (!_db && process.env.DATABASE_URL) {
+    try {
+      _db = drizzle(process.env.DATABASE_URL);
+    } catch (error) {
+      console.warn("[Database] Failed to connect:", error);
+      _db = null;
+    }
+  }
+  return _db;
+}
+
+export async function upsertUser(user: InsertUser): Promise<void> {
+  if (!user.openId) {
+    throw new Error("User openId is required for upsert");
+  }
+
+  const db = await getDb();
+  if (!db) {
+    console.warn("[Database] Cannot upsert user: database not available");
+    return;
+  }
+
+  try {
+    const values: InsertUser = {
+      openId: user.openId,
+    };
+    const updateSet: Record<string, unknown> = {};
+
+    const textFields = ["name", "email", "loginMethod"] as const;
+    type TextField = (typeof textFields)[number];
+
+    const assignNullable = (field: TextField) => {
+      const value = user[field];
+      if (value === undefined) return;
+      const normalized = value ?? null;
+      values[field] = normalized;
+      updateSet[field] = normalized;
+    };
+
+    textFields.forEach(assignNullable);
+
+    if (user.lastSignedIn !== undefined) {
+      values.lastSignedIn = user.lastSignedIn;
+      updateSet.lastSignedIn = user.lastSignedIn;
+    }
+    if (user.role !== undefined) {
+      values.role = user.role;
+      updateSet.role = user.role;
+    } else if (user.openId === ENV.ownerOpenId) {
+      values.role = "admin";
+      updateSet.role = "admin";
+    }
+
+    if (!values.lastSignedIn) {
+      values.lastSignedIn = new Date();
+    }
+
+    if (Object.keys(updateSet).length === 0) {
+      updateSet.lastSignedIn = new Date();
+    }
+
+    await db.insert(users).values(values).onDuplicateKeyUpdate({
+      set: updateSet,
+    });
+  } catch (error) {
+    console.error("[Database] Failed to upsert user:", error);
+    throw error;
+  }
+}
+
+export async function getUserByOpenId(openId: string) {
+  const db = await getDb();
+  if (!db) {
+    console.warn("[Database] Cannot get user: database not available");
+    return undefined;
+  }
+
+  const result = await db.select().from(users).where(eq(users.openId, openId)).limit(1);
+
+  return result.length > 0 ? result[0] : undefined;
+}
+
+// TODO: add feature queries here as your schema grows.
+```
+
+`server/routers.ts`
+```ts
+import { COOKIE_NAME } from "../shared/const.js";
+import { getSessionCookieOptions } from "./_core/cookies";
+import { systemRouter } from "./_core/systemRouter";
+import { publicProcedure, router } from "./_core/trpc";
+
+export const appRouter = router({
+  // if you need to use socket.io, read and register route in server/_core/index.ts, all api should start with '/api/' so that the gateway can route correctly
+  system: systemRouter,
+  auth: router({
+    me: publicProcedure.query((opts) => opts.ctx.user),
+    logout: publicProcedure.mutation(({ ctx }) => {
+      const cookieOptions = getSessionCookieOptions(ctx.req);
+      ctx.res.clearCookie(COOKIE_NAME, { ...cookieOptions, maxAge: -1 });
+      return {
+        success: true,
+      } as const;
+    }),
+  }),
+
+  // TODO: add feature routers here, e.g.
+  // todo: router({
+  //   list: protectedProcedure.query(({ ctx }) =>
+  //     db.getUserTodos(ctx.user.id)
+  //   ),
+  // }),
+});
+
+export type AppRouter = typeof appRouter;
+```
+
+`server/storage.ts`
+```ts
+// Preconfigured storage helpers for Manus WebDev templates
+// Uses the Biz-provided storage proxy (Authorization: Bearer <token>)
+
+import { ENV } from "./_core/env";
+
+type StorageConfig = { baseUrl: string; apiKey: string };
+
+function getStorageConfig(): StorageConfig {
+  const baseUrl = ENV.forgeApiUrl;
+  const apiKey = ENV.forgeApiKey;
+
+  if (!baseUrl || !apiKey) {
+    throw new Error(
+      "Storage proxy credentials missing: set BUILT_IN_FORGE_API_URL and BUILT_IN_FORGE_API_KEY",
+    );
+  }
+
+  return { baseUrl: baseUrl.replace(/\/+$/, ""), apiKey };
+}
+
+function buildUploadUrl(baseUrl: string, relKey: string): URL {
+  const url = new URL("v1/storage/upload", ensureTrailingSlash(baseUrl));
+  url.searchParams.set("path", normalizeKey(relKey));
+  return url;
+}
+
+async function buildDownloadUrl(baseUrl: string, relKey: string, apiKey: string): Promise<string> {
+  const downloadApiUrl = new URL("v1/storage/downloadUrl", ensureTrailingSlash(baseUrl));
+  downloadApiUrl.searchParams.set("path", normalizeKey(relKey));
+  const response = await fetch(downloadApiUrl, {
+    method: "GET",
+    headers: buildAuthHeaders(apiKey),
+  });
+  return (await response.json()).url;
+}
+
+function ensureTrailingSlash(value: string): string {
+  return value.endsWith("/") ? value : `${value}/`;
+}
+
+function normalizeKey(relKey: string): string {
+  return relKey.replace(/^\/+/, "");
+}
+
+function toFormData(
+  data: Buffer | Uint8Array | string,
+  contentType: string,
+  fileName: string,
+): FormData {
+  const blob =
+    typeof data === "string"
+      ? new Blob([data], { type: contentType })
+      : new Blob([data as any], { type: contentType });
+  const form = new FormData();
+  form.append("file", blob, fileName || "file");
+  return form;
+}
+
+function buildAuthHeaders(apiKey: string): HeadersInit {
+  return { Authorization: `Bearer ${apiKey}` };
+}
+
+export async function storagePut(
+  relKey: string,
+  data: Buffer | Uint8Array | string,
+  contentType = "application/octet-stream",
+): Promise<{ key: string; url: string }> {
+  const { baseUrl, apiKey } = getStorageConfig();
+  const key = normalizeKey(relKey);
+  const uploadUrl = buildUploadUrl(baseUrl, key);
+  const formData = toFormData(data, contentType, key.split("/").pop() ?? key);
+  const response = await fetch(uploadUrl, {
+    method: "POST",
+    headers: buildAuthHeaders(apiKey),
+    body: formData,
+  });
+
+  if (!response.ok) {
+    const message = await response.text().catch(() => response.statusText);
+    throw new Error(
+      `Storage upload failed (${response.status} ${response.statusText}): ${message}`,
+    );
+  }
+  const url = (await response.json()).url;
+  return { key, url };
+}
+
+export async function storageGet(relKey: string): Promise<{ key: string; url: string }> {
+  const { baseUrl, apiKey } = getStorageConfig();
+  const key = normalizeKey(relKey);
+  return {
+    key,
+    url: await buildDownloadUrl(baseUrl, key, apiKey),
+  };
+}
+```
+
+`lib/trpc.ts`
+```ts
+import { createTRPCReact } from "@trpc/react-query";
+import { httpBatchLink } from "@trpc/client";
+import superjson from "superjson";
+import type { AppRouter } from "@/server/routers";
+import { getApiBaseUrl } from "@/constants/oauth";
+import * as Auth from "@/lib/_core/auth";
+
+/**
+ * tRPC React client for type-safe API calls.
+ *
+ * IMPORTANT (tRPC v11): The `transformer` must be inside `httpBatchLink`,
+ * NOT at the root createClient level. This ensures client and server
+ * use the same serialization format (superjson).
+ */
+export const trpc = createTRPCReact<AppRouter>();
+
+/**
+ * Creates the tRPC client with proper configuration.
+ * Call this once in your app's root layout.
+ */
+export function createTRPCClient() {
+  return trpc.createClient({
+    links: [
+      httpBatchLink({
+        url: `${getApiBaseUrl()}/api/trpc`,
+        // tRPC v11: transformer MUST be inside httpBatchLink, not at root
+        transformer: superjson,
+        async headers() {
+          const token = await Auth.getSessionToken();
+          return token ? { Authorization: `Bearer ${token}` } : {};
+        },
+        // Custom fetch to include credentials for cookie-based auth
+        fetch(url, options) {
+          return fetch(url, {
+            ...options,
+            credentials: "include",
+          });
+        },
+      }),
+    ],
+  });
+}
+```
+
+`hooks/use-auth.ts`
+```ts
+import * as Api from "@/lib/_core/api";
+import * as Auth from "@/lib/_core/auth";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { Platform } from "react-native";
+
+type UseAuthOptions = {
+  autoFetch?: boolean;
+};
+
+export function useAuth(options?: UseAuthOptions) {
+  const { autoFetch = true } = options ?? {};
+  const [user, setUser] = useState<Auth.User | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  const fetchUser = useCallback(async () => {
+    console.log("[useAuth] fetchUser called");
+    try {
+      setLoading(true);
+      setError(null);
+
+      // Web platform: use cookie-based auth, fetch user from API
+      if (Platform.OS === "web") {
+        console.log("[useAuth] Web platform: fetching user from API...");
+        const apiUser = await Api.getMe();
+        console.log("[useAuth] API user response:", apiUser);
+
+        if (apiUser) {
+          const userInfo: Auth.User = {
+            id: apiUser.id,
+            openId: apiUser.openId,
+            name: apiUser.name,
+            email: apiUser.email,
+            loginMethod: apiUser.loginMethod,
+            lastSignedIn: new Date(apiUser.lastSignedIn),
+          };
+          setUser(userInfo);
+          // Cache user info in localStorage for faster subsequent loads
+          await Auth.setUserInfo(userInfo);
+          console.log("[useAuth] Web user set from API:", userInfo);
+        } else {
+          console.log("[useAuth] Web: No authenticated user from API");
+          setUser(null);
+          await Auth.clearUserInfo();
+        }
+        return;
+      }
+
+      // Native platform: use token-based auth
+      console.log("[useAuth] Native platform: checking for session token...");
+      const sessionToken = await Auth.getSessionToken();
+      console.log(
+        "[useAuth] Session token:",
+        sessionToken ? `present (${sessionToken.substring(0, 20)}...)` : "missing",
+      );
+      if (!sessionToken) {
+        console.log("[useAuth] No session token, setting user to null");
+        setUser(null);
+        return;
+      }
+
+      // Use cached user info for native (token validates the session)
+      const cachedUser = await Auth.getUserInfo();
+      console.log("[useAuth] Cached user:", cachedUser);
+      if (cachedUser) {
+        console.log("[useAuth] Using cached user info");
+        setUser(cachedUser);
+      } else {
+        console.log("[useAuth] No cached user, setting user to null");
+        setUser(null);
+      }
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error("Failed to fetch user");
+      console.error("[useAuth] fetchUser error:", error);
+      setError(error);
+      setUser(null);
+    } finally {
+      setLoading(false);
+      console.log("[useAuth] fetchUser completed, loading:", false);
+    }
+  }, []);
+
+  const logout = useCallback(async () => {
+    try {
+      await Api.logout();
+    } catch (err) {
+      console.error("[Auth] Logout API call failed:", err);
+      // Continue with logout even if API call fails
+    } finally {
+      await Auth.removeSessionToken();
+      await Auth.clearUserInfo();
+      setUser(null);
+      setError(null);
+    }
+  }, []);
+
+  const isAuthenticated = useMemo(() => Boolean(user), [user]);
+
+  useEffect(() => {
+    console.log("[useAuth] useEffect triggered, autoFetch:", autoFetch, "platform:", Platform.OS);
+    if (autoFetch) {
+      if (Platform.OS === "web") {
+        // Web: fetch user from API directly (user will login manually if needed)
+        console.log("[useAuth] Web: fetching user from API...");
+        fetchUser();
+      } else {
+        // Native: check for cached user info first for faster initial load
+        Auth.getUserInfo().then((cachedUser) => {
+          console.log("[useAuth] Native cached user check:", cachedUser);
+          if (cachedUser) {
+            console.log("[useAuth] Native: setting cached user immediately");
+            setUser(cachedUser);
+            setLoading(false);
+          } else {
+            // No cached user, check session token
+            fetchUser();
+          }
+        });
+      }
+    } else {
+      console.log("[useAuth] autoFetch disabled, setting loading to false");
+      setLoading(false);
+    }
+  }, [autoFetch, fetchUser]);
+
+  useEffect(() => {
+    console.log("[useAuth] State updated:", {
+      hasUser: !!user,
+      loading,
+      isAuthenticated,
+      error: error?.message,
+    });
+  }, [user, loading, isAuthenticated, error]);
+
+  return {
+    user,
+    loading,
+    error,
+    isAuthenticated,
+    refresh: fetchUser,
+    logout,
+  };
+}
+```
+
+`tests/auth.logout.test.ts`
+```ts
+import { describe, expect, it } from "vitest";
+import { appRouter } from "../server/routers";
+import { COOKIE_NAME } from "../shared/const";
+import type { TrpcContext } from "../server/_core/context";
+
+type CookieCall = {
+  name: string;
+  options: Record<string, unknown>;
+};
+
+type AuthenticatedUser = NonNullable<TrpcContext["user"]>;
+
+function createAuthContext(): { ctx: TrpcContext; clearedCookies: CookieCall[] } {
+  const clearedCookies: CookieCall[] = [];
+  
+  const user: AuthenticatedUser = {
+    id: 1,
+    openId: "sample-user",
+    email: "sample@example.com",
+    name: "Sample User",
+    loginMethod: "manus",
+    role: "user",
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    lastSignedIn: new Date(),
+  };
+  
+  const ctx: TrpcContext = {
+    user,
+    req: {
+      protocol: "https",
+      headers: {},
+    } as TrpcContext["req"],
+    res: {
+      clearCookie: (name: string, options: Record<string, unknown>) => {
+        clearedCookies.push({ name, options });
+      },
+    } as TrpcContext["res"],
+  };
+  
+  return { ctx, clearedCookies };
+}
+
+// TODO: Remove `.skip` below once you implement user authentication
+describe.skip("auth.logout", () => {
+  it("clears the session cookie and reports success", async () => {
+    const { ctx, clearedCookies } = createAuthContext();
+    const caller = appRouter.createCaller(ctx);
+
+    const result = await caller.auth.logout();
+
+    expect(result).toEqual({ success: true });
+    expect(clearedCookies).toHaveLength(1);
+    expect(clearedCookies[0]?.name).toBe(COOKIE_NAME);
+    expect(clearedCookies[0]?.options).toMatchObject({
+      maxAge: -1,
+      secure: true,
+      sameSite: "none",
+      httpOnly: true,
+      path: "/",
+    });
+  });
+});
+```
+
+---
+
+## Common Patterns
+
+### Optimistic Updates
+
+Update UI immediately, revert on error:
+
+```tsx
+const toggleComplete = trpc.items.update.useMutation({
+  onMutate: async (input) => {
+    // Cancel outgoing queries
+    await utils.items.list.cancel();
+    
+    // Snapshot previous value
+    const previous = utils.items.list.getData();
+    
+    // Optimistically update
+    utils.items.list.setData(undefined, (old) =>
+      old?.map((item) =>
+        item.id === input.id
+          ? { ...item, completed: input.completed }
+          : item
+      )
+    );
+    
+    return { previous };
+  },
+  onError: (err, input, context) => {
+    // Revert on error
+    utils.items.list.setData(undefined, context?.previous);
+  },
+  onSettled: () => {
+    // Refetch after mutation
+    utils.items.list.invalidate();
+  },
+});
+```
+
+### Pagination
+
+```tsx
+// Router
+list: protectedProcedure
+  .input(z.object({
+    limit: z.number().min(1).max(100).default(20),
+    cursor: z.number().optional(),
+  }))
+  .query(async ({ ctx, input }) => {
+    const items = await db.getItems({
+      userId: ctx.user.id,
+      limit: input.limit + 1,
+      cursor: input.cursor,
+    });
+    
+    let nextCursor: number | undefined;
+    if (items.length > input.limit) {
+      const next = items.pop();
+      nextCursor = next?.id;
+    }
+    
+    return { items, nextCursor };
+  }),
+
+// Frontend
+const { data, fetchNextPage, hasNextPage } = trpc.items.list.useInfiniteQuery(
+  { limit: 20 },
+  { getNextPageParam: (lastPage) => lastPage.nextCursor }
+);
+```
+
+---
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| "Database not available" | Check `DATABASE_URL` is set |
+| Auth not working | Verify OAuth callback URL matches |
+| tRPC type errors | Run `pnpm check` to verify types |
+| Mutations fail silently | Check browser console for errors |
+| Session expired | User needs to login again |

server/_core/context.ts

@@ -0,0 +1,26 @@
+import type { CreateExpressContextOptions } from "@trpc/server/adapters/express";
+import type { User } from "../../drizzle/schema";
+import { sdk } from "./sdk";
+
+export type TrpcContext = {
+  req: CreateExpressContextOptions["req"];
+  res: CreateExpressContextOptions["res"];
+  user: User | null;
+};
+
+export async function createContext(opts: CreateExpressContextOptions): Promise<TrpcContext> {
+  let user: User | null = null;
+
+  try {
+    user = await sdk.authenticateRequest(opts.req);
+  } catch (error) {
+    // Authentication is optional for public procedures.
+    user = null;
+  }
+
+  return {
+    req: opts.req,
+    res: opts.res,
+    user,
+  };
+}

server/_core/cookies.ts

@@ -0,0 +1,60 @@
+import type { CookieOptions, Request } from "express";
+
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "::1"]);
+
+function isIpAddress(host: string) {
+  // Basic IPv4 check and IPv6 presence detection.
+  if (/^\d{1,3}(\.\d{1,3}){3}$/.test(host)) return true;
+  return host.includes(":");
+}
+
+function isSecureRequest(req: Request) {
+  if (req.protocol === "https") return true;
+
+  const forwardedProto = req.headers["x-forwarded-proto"];
+  if (!forwardedProto) return false;
+
+  const protoList = Array.isArray(forwardedProto) ? forwardedProto : forwardedProto.split(",");
+
+  return protoList.some((proto) => proto.trim().toLowerCase() === "https");
+}
+
+/**
+ * Extract parent domain for cookie sharing across subdomains.
+ * e.g., "3000-xxx.manuspre.computer" -> ".manuspre.computer"
+ * This allows cookies set by 3000-xxx to be read by 8081-xxx
+ */
+function getParentDomain(hostname: string): string | undefined {
+  // Don't set domain for localhost or IP addresses
+  if (LOCAL_HOSTS.has(hostname) || isIpAddress(hostname)) {
+    return undefined;
+  }
+
+  // Split hostname into parts
+  const parts = hostname.split(".");
+
+  // Need at least 3 parts for a subdomain (e.g., "3000-xxx.manuspre.computer")
+  // For "manuspre.computer", we can't set a parent domain
+  if (parts.length < 3) {
+    return undefined;
+  }
+
+  // Return parent domain with leading dot (e.g., ".manuspre.computer")
+  // This allows cookie to be shared across all subdomains
+  return "." + parts.slice(-2).join(".");
+}
+
+export function getSessionCookieOptions(
+  req: Request,
+): Pick<CookieOptions, "domain" | "httpOnly" | "path" | "sameSite" | "secure"> {
+  const hostname = req.hostname;
+  const domain = getParentDomain(hostname);
+
+  return {
+    domain,
+    httpOnly: true,
+    path: "/",
+    sameSite: "none",
+    secure: isSecureRequest(req),
+  };
+}

server/_core/dataApi.ts

@@ -0,0 +1,64 @@
+/**
+ * Quick example (matches curl usage):
+ *   await callDataApi("Youtube/search", {
+ *     query: { gl: "US", hl: "en", q: "manus" },
+ *   })
+ */
+import { ENV } from "./env";
+
+export type DataApiCallOptions = {
+  query?: Record<string, unknown>;
+  body?: Record<string, unknown>;
+  pathParams?: Record<string, unknown>;
+  formData?: Record<string, unknown>;
+};
+
+export async function callDataApi(
+  apiId: string,
+  options: DataApiCallOptions = {},
+): Promise<unknown> {
+  if (!ENV.forgeApiUrl) {
+    throw new Error("BUILT_IN_FORGE_API_URL is not configured");
+  }
+  if (!ENV.forgeApiKey) {
+    throw new Error("BUILT_IN_FORGE_API_KEY is not configured");
+  }
+
+  // Build the full URL by appending the service path to the base URL
+  const baseUrl = ENV.forgeApiUrl.endsWith("/") ? ENV.forgeApiUrl : `${ENV.forgeApiUrl}/`;
+  const fullUrl = new URL("webdevtoken.v1.WebDevService/CallApi", baseUrl).toString();
+
+  const response = await fetch(fullUrl, {
+    method: "POST",
+    headers: {
+      accept: "application/json",
+      "content-type": "application/json",
+      "connect-protocol-version": "1",
+      authorization: `Bearer ${ENV.forgeApiKey}`,
+    },
+    body: JSON.stringify({
+      apiId,
+      query: options.query,
+      body: options.body,
+      path_params: options.pathParams,
+      multipart_form_data: options.formData,
+    }),
+  });
+
+  if (!response.ok) {
+    const detail = await response.text().catch(() => "");
+    throw new Error(
+      `Data API request failed (${response.status} ${response.statusText})${detail ? `: ${detail}` : ""}`,
+    );
+  }
+
+  const payload = await response.json().catch(() => ({}));
+  if (payload && typeof payload === "object" && "jsonData" in payload) {
+    try {
+      return JSON.parse((payload as Record<string, string>).jsonData ?? "{}");
+    } catch {
+      return (payload as Record<string, unknown>).jsonData;
+    }
+  }
+  return payload;
+}

server/_core/env.ts

@@ -0,0 +1,10 @@
+export const ENV = {
+  appId: process.env.VITE_APP_ID ?? "",
+  cookieSecret: process.env.JWT_SECRET ?? "",
+  databaseUrl: process.env.DATABASE_URL ?? "",
+  oAuthServerUrl: process.env.OAUTH_SERVER_URL ?? "",
+  ownerOpenId: process.env.OWNER_OPEN_ID ?? "",
+  isProduction: process.env.NODE_ENV === "production",
+  forgeApiUrl: process.env.BUILT_IN_FORGE_API_URL ?? "",
+  forgeApiKey: process.env.BUILT_IN_FORGE_API_KEY ?? "",
+};

server/_core/imageGeneration.ts

@@ -0,0 +1,81 @@
+/**
+ * Image generation helper using internal ImageService
+ *
+ * Example usage:
+ *   const { url: imageUrl } = await generateImage({
+ *     prompt: "A serene landscape with mountains"
+ *   });
+ *
+ * For editing:
+ *   const { url: imageUrl } = await generateImage({
+ *     prompt: "Add a rainbow to this landscape",
+ *     originalImages: [{
+ *       url: "https://example.com/original.jpg",
+ *       mimeType: "image/jpeg"
+ *     }]
+ *   });
+ */
+import { storagePut } from "../storage";
+import { ENV } from "./env";
+
+export type GenerateImageOptions = {
+  prompt: string;
+  originalImages?: Array<{
+    url?: string;
+    b64Json?: string;
+    mimeType?: string;
+  }>;
+};
+
+export type GenerateImageResponse = {
+  url?: string;
+};
+
+export async function generateImage(options: GenerateImageOptions): Promise<GenerateImageResponse> {
+  if (!ENV.forgeApiUrl) {
+    throw new Error("BUILT_IN_FORGE_API_URL is not configured");
+  }
+  if (!ENV.forgeApiKey) {
+    throw new Error("BUILT_IN_FORGE_API_KEY is not configured");
+  }
+
+  // Build the full URL by appending the service path to the base URL
+  const baseUrl = ENV.forgeApiUrl.endsWith("/") ? ENV.forgeApiUrl : `${ENV.forgeApiUrl}/`;
+  const fullUrl = new URL("images.v1.ImageService/GenerateImage", baseUrl).toString();
+
+  const response = await fetch(fullUrl, {
+    method: "POST",
+    headers: {
+      accept: "application/json",
+      "content-type": "application/json",
+      "connect-protocol-version": "1",
+      authorization: `Bearer ${ENV.forgeApiKey}`,
+    },
+    body: JSON.stringify({
+      prompt: options.prompt,
+      original_images: options.originalImages || [],
+    }),
+  });
+
+  if (!response.ok) {
+    const detail = await response.text().catch(() => "");
+    throw new Error(
+      `Image generation request failed (${response.status} ${response.statusText})${detail ? `: ${detail}` : ""}`,
+    );
+  }
+
+  const result = (await response.json()) as {
+    image: {
+      b64Json: string;
+      mimeType: string;
+    };
+  };
+  const base64Data = result.image.b64Json;
+  const buffer = Buffer.from(base64Data, "base64");
+
+  // Save to S3
+  const { url } = await storagePut(`generated/${Date.now()}.png`, buffer, result.image.mimeType);
+  return {
+    url,
+  };
+}

server/_core/index.ts

@@ -0,0 +1,97 @@
+import "dotenv/config";
+import express from "express";
+import { createServer } from "http";
+import net from "net";
+import { createExpressMiddleware } from "@trpc/server/adapters/express";
+import { registerOAuthRoutes } from "./oauth";
+import { appRouter } from "../routers";
+import { createContext } from "./context";
+import { registerVoiceWebSocket } from "../voice-ws";
+
+function isPortAvailable(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.listen(port, "0.0.0.0", () => {
+      server.close(() => resolve(true));
+    });
+    server.on("error", () => resolve(false));
+  });
+}
+
+async function findAvailablePort(startPort: number = 3000): Promise<number> {
+  for (let port = startPort; port < startPort + 20; port++) {
+    if (await isPortAvailable(port)) {
+      return port;
+    }
+  }
+  throw new Error(`No available port found starting from ${startPort}`);
+}
+
+async function startServer() {
+  const app = express();
+  const server = createServer(app);
+
+  // Enable CORS for all routes
+  // In production, restrict to known origins; in dev, reflect any origin.
+  const ALLOWED_ORIGINS = process.env.CORS_ORIGINS
+    ? process.env.CORS_ORIGINS.split(",").map((o) => o.trim())
+    : null; // null = allow all (dev mode)
+
+  app.use((req, res, next) => {
+    const origin = req.headers.origin;
+    if (origin) {
+      const isAllowed = !ALLOWED_ORIGINS || ALLOWED_ORIGINS.includes(origin);
+      if (isAllowed) {
+        res.header("Access-Control-Allow-Origin", origin);
+      }
+    }
+    res.header("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
+    res.header(
+      "Access-Control-Allow-Headers",
+      "Origin, X-Requested-With, Content-Type, Accept, Authorization",
+    );
+    res.header("Access-Control-Allow-Credentials", "true");
+
+    // Handle preflight requests
+    if (req.method === "OPTIONS") {
+      res.sendStatus(200);
+      return;
+    }
+    next();
+  });
+
+  app.use(express.json({ limit: "50mb" }));
+  app.use(express.urlencoded({ limit: "50mb", extended: true }));
+
+  registerOAuthRoutes(app);
+
+  app.get("/api/health", (_req, res) => {
+    res.json({ ok: true, timestamp: Date.now() });
+  });
+
+  app.use(
+    "/api/trpc",
+    createExpressMiddleware({
+      router: appRouter,
+      createContext,
+    }),
+  );
+
+  const preferredPort = parseInt(process.env.PORT || "3000");
+  const port = await findAvailablePort(preferredPort);
+
+  if (port !== preferredPort) {
+    console.warn(`⚠️  Port ${preferredPort} is busy, using port ${port} instead`);
+    console.warn(`⚠️  Update EXPO_PUBLIC_API_BASE_URL in .env to use port ${port}`);
+  }
+
+  // تسجيل WebSocket للتعرف الفوري على الصوت
+  registerVoiceWebSocket(server);
+
+  server.listen(port, "0.0.0.0", () => {
+    console.log(`[api] server listening on http://0.0.0.0:${port}`);
+    console.log(`[api] LAN clients should connect to http://<YOUR_PC_IP>:${port}`);
+  });
+}
+
+startServer().catch(console.error);

server/_core/llm.ts

@@ -0,0 +1,314 @@
+import { ENV } from "./env";
+
+export type Role = "system" | "user" | "assistant" | "tool" | "function";
+
+export type TextContent = {
+  type: "text";
+  text: string;
+};
+
+export type ImageContent = {
+  type: "image_url";
+  image_url: {
+    url: string;
+    detail?: "auto" | "low" | "high";
+  };
+};
+
+export type FileContent = {
+  type: "file_url";
+  file_url: {
+    url: string;
+    mime_type?: "audio/mpeg" | "audio/wav" | "application/pdf" | "audio/mp4" | "video/mp4";
+  };
+};
+
+export type MessageContent = string | TextContent | ImageContent | FileContent;
+
+export type Message = {
+  role: Role;
+  content: MessageContent | MessageContent[];
+  name?: string;
+  tool_call_id?: string;
+};
+
+export type Tool = {
+  type: "function";
+  function: {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+  };
+};
+
+export type ToolChoicePrimitive = "none" | "auto" | "required";
+export type ToolChoiceByName = { name: string };
+export type ToolChoiceExplicit = {
+  type: "function";
+  function: {
+    name: string;
+  };
+};
+
+export type ToolChoice = ToolChoicePrimitive | ToolChoiceByName | ToolChoiceExplicit;
+
+export type InvokeParams = {
+  messages: Message[];
+  tools?: Tool[];
+  toolChoice?: ToolChoice;
+  tool_choice?: ToolChoice;
+  maxTokens?: number;
+  max_tokens?: number;
+  outputSchema?: OutputSchema;
+  output_schema?: OutputSchema;
+  responseFormat?: ResponseFormat;
+  response_format?: ResponseFormat;
+};
+
+export type ToolCall = {
+  id: string;
+  type: "function";
+  function: {
+    name: string;
+    arguments: string;
+  };
+};
+
+export type InvokeResult = {
+  id: string;
+  created: number;
+  model: string;
+  choices: Array<{
+    index: number;
+    message: {
+      role: Role;
+      content: string | Array<TextContent | ImageContent | FileContent>;
+      tool_calls?: ToolCall[];
+    };
+    finish_reason: string | null;
+  }>;
+  usage?: {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+  };
+};
+
+export type JsonSchema = {
+  name: string;
+  schema: Record<string, unknown>;
+  strict?: boolean;
+};
+
+export type OutputSchema = JsonSchema;
+
+export type ResponseFormat =
+  | { type: "text" }
+  | { type: "json_object" }
+  | { type: "json_schema"; json_schema: JsonSchema };
+
+const ensureArray = (value: MessageContent | MessageContent[]): MessageContent[] =>
+  Array.isArray(value) ? value : [value];
+
+const normalizeContentPart = (part: MessageContent): TextContent | ImageContent | FileContent => {
+  if (typeof part === "string") {
+    return { type: "text", text: part };
+  }
+
+  if (part.type === "text") {
+    return part;
+  }
+
+  if (part.type === "image_url") {
+    return part;
+  }
+
+  if (part.type === "file_url") {
+    return part;
+  }
+
+  throw new Error("Unsupported message content part");
+};
+
+const normalizeMessage = (message: Message) => {
+  const { role, name, tool_call_id } = message;
+
+  if (role === "tool" || role === "function") {
+    const content = ensureArray(message.content)
+      .map((part) => (typeof part === "string" ? part : JSON.stringify(part)))
+      .join("\n");
+
+    return {
+      role,
+      name,
+      tool_call_id,
+      content,
+    };
+  }
+
+  const contentParts = ensureArray(message.content).map(normalizeContentPart);
+
+  // If there's only text content, collapse to a single string for compatibility
+  if (contentParts.length === 1 && contentParts[0].type === "text") {
+    return {
+      role,
+      name,
+      content: contentParts[0].text,
+    };
+  }
+
+  return {
+    role,
+    name,
+    content: contentParts,
+  };
+};
+
+const normalizeToolChoice = (
+  toolChoice: ToolChoice | undefined,
+  tools: Tool[] | undefined,
+): "none" | "auto" | ToolChoiceExplicit | undefined => {
+  if (!toolChoice) return undefined;
+
+  if (toolChoice === "none" || toolChoice === "auto") {
+    return toolChoice;
+  }
+
+  if (toolChoice === "required") {
+    if (!tools || tools.length === 0) {
+      throw new Error("tool_choice 'required' was provided but no tools were configured");
+    }
+
+    if (tools.length > 1) {
+      throw new Error(
+        "tool_choice 'required' needs a single tool or specify the tool name explicitly",
+      );
+    }
+
+    return {
+      type: "function",
+      function: { name: tools[0].function.name },
+    };
+  }
+
+  if ("name" in toolChoice) {
+    return {
+      type: "function",
+      function: { name: toolChoice.name },
+    };
+  }
+
+  return toolChoice;
+};
+
+const resolveApiUrl = () =>
+  ENV.forgeApiUrl && ENV.forgeApiUrl.trim().length > 0
+    ? `${ENV.forgeApiUrl.replace(/\/$/, "")}/v1/chat/completions`
+    : "https://forge.manus.im/v1/chat/completions";
+
+const assertApiKey = () => {
+  if (!ENV.forgeApiKey) {
+    throw new Error("OPENAI_API_KEY is not configured");
+  }
+};
+
+const normalizeResponseFormat = ({
+  responseFormat,
+  response_format,
+  outputSchema,
+  output_schema,
+}: {
+  responseFormat?: ResponseFormat;
+  response_format?: ResponseFormat;
+  outputSchema?: OutputSchema;
+  output_schema?: OutputSchema;
+}):
+  | { type: "json_schema"; json_schema: JsonSchema }
+  | { type: "text" }
+  | { type: "json_object" }
+  | undefined => {
+  const explicitFormat = responseFormat || response_format;
+  if (explicitFormat) {
+    if (explicitFormat.type === "json_schema" && !explicitFormat.json_schema?.schema) {
+      throw new Error("responseFormat json_schema requires a defined schema object");
+    }
+    return explicitFormat;
+  }
+
+  const schema = outputSchema || output_schema;
+  if (!schema) return undefined;
+
+  if (!schema.name || !schema.schema) {
+    throw new Error("outputSchema requires both name and schema");
+  }
+
+  return {
+    type: "json_schema",
+    json_schema: {
+      name: schema.name,
+      schema: schema.schema,
+      ...(typeof schema.strict === "boolean" ? { strict: schema.strict } : {}),
+    },
+  };
+};
+
+export async function invokeLLM(params: InvokeParams): Promise<InvokeResult> {
+  assertApiKey();
+
+  const {
+    messages,
+    tools,
+    toolChoice,
+    tool_choice,
+    outputSchema,
+    output_schema,
+    responseFormat,
+    response_format,
+  } = params;
+
+  const payload: Record<string, unknown> = {
+    model: "gemini-2.5-flash",
+    messages: messages.map(normalizeMessage),
+  };
+
+  if (tools && tools.length > 0) {
+    payload.tools = tools;
+  }
+
+  const normalizedToolChoice = normalizeToolChoice(toolChoice || tool_choice, tools);
+  if (normalizedToolChoice) {
+    payload.tool_choice = normalizedToolChoice;
+  }
+
+  payload.max_tokens = 32768;
+  payload.thinking = {
+    budget_tokens: 128,
+  };
+
+  const normalizedResponseFormat = normalizeResponseFormat({
+    responseFormat,
+    response_format,
+    outputSchema,
+    output_schema,
+  });
+
+  if (normalizedResponseFormat) {
+    payload.response_format = normalizedResponseFormat;
+  }
+
+  const response = await fetch(resolveApiUrl(), {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      authorization: `Bearer ${ENV.forgeApiKey}`,
+    },
+    body: JSON.stringify(payload),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`LLM invoke failed: ${response.status} ${response.statusText} – ${errorText}`);
+  }
+
+  return (await response.json()) as InvokeResult;
+}

server/_core/notification.ts

@@ -0,0 +1,107 @@
+import { TRPCError } from "@trpc/server";
+import { ENV } from "./env";
+
+export type NotificationPayload = {
+  title: string;
+  content: string;
+};
+
+const TITLE_MAX_LENGTH = 1200;
+const CONTENT_MAX_LENGTH = 20000;
+
+const trimValue = (value: string): string => value.trim();
+const isNonEmptyString = (value: unknown): value is string =>
+  typeof value === "string" && value.trim().length > 0;
+
+const buildEndpointUrl = (baseUrl: string): string => {
+  const normalizedBase = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+  return new URL("webdevtoken.v1.WebDevService/SendNotification", normalizedBase).toString();
+};
+
+const validatePayload = (input: NotificationPayload): NotificationPayload => {
+  if (!isNonEmptyString(input.title)) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "Notification title is required.",
+    });
+  }
+  if (!isNonEmptyString(input.content)) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "Notification content is required.",
+    });
+  }
+
+  const title = trimValue(input.title);
+  const content = trimValue(input.content);
+
+  if (title.length > TITLE_MAX_LENGTH) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: `Notification title must be at most ${TITLE_MAX_LENGTH} characters.`,
+    });
+  }
+
+  if (content.length > CONTENT_MAX_LENGTH) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: `Notification content must be at most ${CONTENT_MAX_LENGTH} characters.`,
+    });
+  }
+
+  return { title, content };
+};
+
+/**
+ * Dispatches a project-owner notification through the Manus Notification Service.
+ * Returns `true` if the request was accepted, `false` when the upstream service
+ * cannot be reached (callers can fall back to email/slack). Validation errors
+ * bubble up as TRPC errors so callers can fix the payload.
+ */
+export async function notifyOwner(payload: NotificationPayload): Promise<boolean> {
+  const { title, content } = validatePayload(payload);
+
+  if (!ENV.forgeApiUrl) {
+    throw new TRPCError({
+      code: "INTERNAL_SERVER_ERROR",
+      message: "Notification service URL is not configured.",
+    });
+  }
+
+  if (!ENV.forgeApiKey) {
+    throw new TRPCError({
+      code: "INTERNAL_SERVER_ERROR",
+      message: "Notification service API key is not configured.",
+    });
+  }
+
+  const endpoint = buildEndpointUrl(ENV.forgeApiUrl);
+
+  try {
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        accept: "application/json",
+        authorization: `Bearer ${ENV.forgeApiKey}`,
+        "content-type": "application/json",
+        "connect-protocol-version": "1",
+      },
+      body: JSON.stringify({ title, content }),
+    });
+
+    if (!response.ok) {
+      const detail = await response.text().catch(() => "");
+      console.warn(
+        `[Notification] Failed to notify owner (${response.status} ${response.statusText})${
+          detail ? `: ${detail}` : ""
+        }`,
+      );
+      return false;
+    }
+
+    return true;
+  } catch (error) {
+    console.warn("[Notification] Error calling notification service:", error);
+    return false;
+  }
+}

server/_core/oauth.ts

@@ -0,0 +1,174 @@
+import { COOKIE_NAME, ONE_YEAR_MS } from "../../shared/const.js";
+import type { Express, Request, Response } from "express";
+import { getUserByOpenId, upsertUser } from "../db";
+import { getSessionCookieOptions } from "./cookies";
+import { sdk } from "./sdk";
+
+function getQueryParam(req: Request, key: string): string | undefined {
+  const value = req.query[key];
+  return typeof value === "string" ? value : undefined;
+}
+
+async function syncUser(userInfo: {
+  openId?: string | null;
+  name?: string | null;
+  email?: string | null;
+  loginMethod?: string | null;
+  platform?: string | null;
+}) {
+  if (!userInfo.openId) {
+    throw new Error("openId missing from user info");
+  }
+
+  const lastSignedIn = new Date();
+  await upsertUser({
+    openId: userInfo.openId,
+    name: userInfo.name || null,
+    email: userInfo.email ?? null,
+    loginMethod: userInfo.loginMethod ?? userInfo.platform ?? null,
+    lastSignedIn,
+  });
+  const saved = await getUserByOpenId(userInfo.openId);
+  return (
+    saved ?? {
+      openId: userInfo.openId,
+      name: userInfo.name,
+      email: userInfo.email,
+      loginMethod: userInfo.loginMethod ?? null,
+      lastSignedIn,
+    }
+  );
+}
+
+function buildUserResponse(
+  user:
+    | Awaited<ReturnType<typeof getUserByOpenId>>
+    | {
+        openId: string;
+        name?: string | null;
+        email?: string | null;
+        loginMethod?: string | null;
+        lastSignedIn?: Date | null;
+      },
+) {
+  return {
+    id: (user as any)?.id ?? null,
+    openId: user?.openId ?? null,
+    name: user?.name ?? null,
+    email: user?.email ?? null,
+    loginMethod: user?.loginMethod ?? null,
+    lastSignedIn: (user?.lastSignedIn ?? new Date()).toISOString(),
+  };
+}
+
+export function registerOAuthRoutes(app: Express) {
+  app.get("/api/oauth/callback", async (req: Request, res: Response) => {
+    const code = getQueryParam(req, "code");
+    const state = getQueryParam(req, "state");
+
+    if (!code || !state) {
+      res.status(400).json({ error: "code and state are required" });
+      return;
+    }
+
+    try {
+      const tokenResponse = await sdk.exchangeCodeForToken(code, state);
+      const userInfo = await sdk.getUserInfo(tokenResponse.accessToken);
+      await syncUser(userInfo);
+      const sessionToken = await sdk.createSessionToken(userInfo.openId!, {
+        name: userInfo.name || "",
+        expiresInMs: ONE_YEAR_MS,
+      });
+
+      const cookieOptions = getSessionCookieOptions(req);
+      res.cookie(COOKIE_NAME, sessionToken, { ...cookieOptions, maxAge: ONE_YEAR_MS });
+
+      // Redirect to the frontend URL (Expo web on port 8081)
+      // Cookie is set with parent domain so it works across both 3000 and 8081 subdomains
+      const frontendUrl =
+        process.env.EXPO_WEB_PREVIEW_URL ||
+        process.env.EXPO_PACKAGER_PROXY_URL ||
+        "http://localhost:8081";
+      res.redirect(302, frontendUrl);
+    } catch (error) {
+      console.error("[OAuth] Callback failed", error);
+      res.status(500).json({ error: "OAuth callback failed" });
+    }
+  });
+
+  app.get("/api/oauth/mobile", async (req: Request, res: Response) => {
+    const code = getQueryParam(req, "code");
+    const state = getQueryParam(req, "state");
+
+    if (!code || !state) {
+      res.status(400).json({ error: "code and state are required" });
+      return;
+    }
+
+    try {
+      const tokenResponse = await sdk.exchangeCodeForToken(code, state);
+      const userInfo = await sdk.getUserInfo(tokenResponse.accessToken);
+      const user = await syncUser(userInfo);
+
+      const sessionToken = await sdk.createSessionToken(userInfo.openId!, {
+        name: userInfo.name || "",
+        expiresInMs: ONE_YEAR_MS,
+      });
+
+      const cookieOptions = getSessionCookieOptions(req);
+      res.cookie(COOKIE_NAME, sessionToken, { ...cookieOptions, maxAge: ONE_YEAR_MS });
+
+      res.json({
+        app_session_id: sessionToken,
+        user: buildUserResponse(user),
+      });
+    } catch (error) {
+      console.error("[OAuth] Mobile exchange failed", error);
+      res.status(500).json({ error: "OAuth mobile exchange failed" });
+    }
+  });
+
+  app.post("/api/auth/logout", (req: Request, res: Response) => {
+    const cookieOptions = getSessionCookieOptions(req);
+    res.clearCookie(COOKIE_NAME, { ...cookieOptions, maxAge: -1 });
+    res.json({ success: true });
+  });
+
+  // Get current authenticated user - works with both cookie (web) and Bearer token (mobile)
+  app.get("/api/auth/me", async (req: Request, res: Response) => {
+    try {
+      const user = await sdk.authenticateRequest(req);
+      res.json({ user: buildUserResponse(user) });
+    } catch (error) {
+      console.error("[Auth] /api/auth/me failed:", error);
+      res.status(401).json({ error: "Not authenticated", user: null });
+    }
+  });
+
+  // Establish session cookie from Bearer token
+  // Used by iframe preview: frontend receives token via postMessage, then calls this endpoint
+  // to get a proper Set-Cookie response from the backend (3000-xxx domain)
+  app.post("/api/auth/session", async (req: Request, res: Response) => {
+    try {
+      // Authenticate using Bearer token from Authorization header
+      const user = await sdk.authenticateRequest(req);
+
+      // Get the token from the Authorization header to set as cookie
+      const authHeader = req.headers.authorization || req.headers.Authorization;
+      if (typeof authHeader !== "string" || !authHeader.startsWith("Bearer ")) {
+        res.status(400).json({ error: "Bearer token required" });
+        return;
+      }
+      const token = authHeader.slice("Bearer ".length).trim();
+
+      // Set cookie for this domain (3000-xxx)
+      const cookieOptions = getSessionCookieOptions(req);
+      res.cookie(COOKIE_NAME, token, { ...cookieOptions, maxAge: ONE_YEAR_MS });
+
+      res.json({ success: true, user: buildUserResponse(user) });
+    } catch (error) {
+      console.error("[Auth] /api/auth/session failed:", error);
+      res.status(401).json({ error: "Invalid token" });
+    }
+  });
+}

server/_core/sdk.ts

@@ -0,0 +1,285 @@
+import { AXIOS_TIMEOUT_MS, COOKIE_NAME, ONE_YEAR_MS } from "../../shared/const.js";
+import { ForbiddenError } from "../../shared/_core/errors.js";
+import axios, { type AxiosInstance } from "axios";
+import { parse as parseCookieHeader } from "cookie";
+import type { Request } from "express";
+import { SignJWT, jwtVerify } from "jose";
+import type { User } from "../../drizzle/schema";
+import * as db from "../db";
+import { ENV } from "./env";
+import type {
+  ExchangeTokenRequest,
+  ExchangeTokenResponse,
+  GetUserInfoResponse,
+  GetUserInfoWithJwtRequest,
+  GetUserInfoWithJwtResponse,
+} from "./types/manusTypes";
+// Utility function
+const isNonEmptyString = (value: unknown): value is string =>
+  typeof value === "string" && value.length > 0;
+
+export type SessionPayload = {
+  openId: string;
+  appId: string;
+  name: string;
+};
+
+const EXCHANGE_TOKEN_PATH = `/webdev.v1.WebDevAuthPublicService/ExchangeToken`;
+const GET_USER_INFO_PATH = `/webdev.v1.WebDevAuthPublicService/GetUserInfo`;
+const GET_USER_INFO_WITH_JWT_PATH = `/webdev.v1.WebDevAuthPublicService/GetUserInfoWithJwt`;
+
+class OAuthService {
+  constructor(private client: ReturnType<typeof axios.create>) {
+    console.log("[OAuth] Initialized with baseURL:", ENV.oAuthServerUrl);
+    if (!ENV.oAuthServerUrl) {
+      console.error(
+        "[OAuth] ERROR: OAUTH_SERVER_URL is not configured! Set OAUTH_SERVER_URL environment variable.",
+      );
+    }
+  }
+
+  private decodeState(state: string): string {
+    const redirectUri = atob(state);
+    return redirectUri;
+  }
+
+  async getTokenByCode(code: string, state: string): Promise<ExchangeTokenResponse> {
+    const payload: ExchangeTokenRequest = {
+      clientId: ENV.appId,
+      grantType: "authorization_code",
+      code,
+      redirectUri: this.decodeState(state),
+    };
+
+    const { data } = await this.client.post<ExchangeTokenResponse>(EXCHANGE_TOKEN_PATH, payload);
+
+    return data;
+  }
+
+  async getUserInfoByToken(token: ExchangeTokenResponse): Promise<GetUserInfoResponse> {
+    const { data } = await this.client.post<GetUserInfoResponse>(GET_USER_INFO_PATH, {
+      accessToken: token.accessToken,
+    });
+
+    return data;
+  }
+}
+
+const createOAuthHttpClient = (): AxiosInstance =>
+  axios.create({
+    baseURL: ENV.oAuthServerUrl,
+    timeout: AXIOS_TIMEOUT_MS,
+  });
+
+class SDKServer {
+  private readonly client: AxiosInstance;
+  private readonly oauthService: OAuthService;
+
+  constructor(client: AxiosInstance = createOAuthHttpClient()) {
+    this.client = client;
+    this.oauthService = new OAuthService(this.client);
+  }
+
+  private deriveLoginMethod(
+    platforms: unknown,
+    fallback: string | null | undefined,
+  ): string | null {
+    if (fallback && fallback.length > 0) return fallback;
+    if (!Array.isArray(platforms) || platforms.length === 0) return null;
+    const set = new Set<string>(platforms.filter((p): p is string => typeof p === "string"));
+    if (set.has("REGISTERED_PLATFORM_EMAIL")) return "email";
+    if (set.has("REGISTERED_PLATFORM_GOOGLE")) return "google";
+    if (set.has("REGISTERED_PLATFORM_APPLE")) return "apple";
+    if (set.has("REGISTERED_PLATFORM_MICROSOFT") || set.has("REGISTERED_PLATFORM_AZURE"))
+      return "microsoft";
+    if (set.has("REGISTERED_PLATFORM_GITHUB")) return "github";
+    const first = Array.from(set)[0];
+    return first ? first.toLowerCase() : null;
+  }
+
+  /**
+   * Exchange OAuth authorization code for access token
+   * @example
+   * const tokenResponse = await sdk.exchangeCodeForToken(code, state);
+   */
+  async exchangeCodeForToken(code: string, state: string): Promise<ExchangeTokenResponse> {
+    return this.oauthService.getTokenByCode(code, state);
+  }
+
+  /**
+   * Get user information using access token
+   * @example
+   * const userInfo = await sdk.getUserInfo(tokenResponse.accessToken);
+   */
+  async getUserInfo(accessToken: string): Promise<GetUserInfoResponse> {
+    const data = await this.oauthService.getUserInfoByToken({
+      accessToken,
+    } as ExchangeTokenResponse);
+    const loginMethod = this.deriveLoginMethod(
+      (data as any)?.platforms,
+      (data as any)?.platform ?? data.platform ?? null,
+    );
+    return {
+      ...(data as any),
+      platform: loginMethod,
+      loginMethod,
+    } as GetUserInfoResponse;
+  }
+
+  private parseCookies(cookieHeader: string | undefined) {
+    if (!cookieHeader) {
+      return new Map<string, string>();
+    }
+
+    const parsed = parseCookieHeader(cookieHeader);
+    return new Map(Object.entries(parsed));
+  }
+
+  private getSessionSecret() {
+    const secret = ENV.cookieSecret;
+    return new TextEncoder().encode(secret);
+  }
+
+  /**
+   * Create a session token for a Manus user openId
+   * @example
+   * const sessionToken = await sdk.createSessionToken(userInfo.openId);
+   */
+  async createSessionToken(
+    openId: string,
+    options: { expiresInMs?: number; name?: string } = {},
+  ): Promise<string> {
+    return this.signSession(
+      {
+        openId,
+        appId: ENV.appId,
+        name: options.name || "",
+      },
+      options,
+    );
+  }
+
+  async signSession(
+    payload: SessionPayload,
+    options: { expiresInMs?: number } = {},
+  ): Promise<string> {
+    const issuedAt = Date.now();
+    const expiresInMs = options.expiresInMs ?? ONE_YEAR_MS;
+    const expirationSeconds = Math.floor((issuedAt + expiresInMs) / 1000);
+    const secretKey = this.getSessionSecret();
+
+    return new SignJWT({
+      openId: payload.openId,
+      appId: payload.appId,
+      name: payload.name,
+    })
+      .setProtectedHeader({ alg: "HS256", typ: "JWT" })
+      .setExpirationTime(expirationSeconds)
+      .sign(secretKey);
+  }
+
+  async verifySession(
+    cookieValue: string | undefined | null,
+  ): Promise<{ openId: string; appId: string; name: string } | null> {
+    if (!cookieValue) {
+      console.warn("[Auth] Missing session cookie");
+      return null;
+    }
+
+    try {
+      const secretKey = this.getSessionSecret();
+      const { payload } = await jwtVerify(cookieValue, secretKey, {
+        algorithms: ["HS256"],
+      });
+      const { openId, appId, name } = payload as Record<string, unknown>;
+
+      if (!isNonEmptyString(openId) || !isNonEmptyString(appId) || !isNonEmptyString(name)) {
+        console.warn("[Auth] Session payload missing required fields");
+        return null;
+      }
+
+      return {
+        openId,
+        appId,
+        name,
+      };
+    } catch (error) {
+      console.warn("[Auth] Session verification failed", String(error));
+      return null;
+    }
+  }
+
+  async getUserInfoWithJwt(jwtToken: string): Promise<GetUserInfoWithJwtResponse> {
+    const payload: GetUserInfoWithJwtRequest = {
+      jwtToken,
+      projectId: ENV.appId,
+    };
+
+    const { data } = await this.client.post<GetUserInfoWithJwtResponse>(
+      GET_USER_INFO_WITH_JWT_PATH,
+      payload,
+    );
+
+    const loginMethod = this.deriveLoginMethod(
+      (data as any)?.platforms,
+      (data as any)?.platform ?? data.platform ?? null,
+    );
+    return {
+      ...(data as any),
+      platform: loginMethod,
+      loginMethod,
+    } as GetUserInfoWithJwtResponse;
+  }
+
+  async authenticateRequest(req: Request): Promise<User> {
+    // Regular authentication flow
+    const authHeader = req.headers.authorization || req.headers.Authorization;
+    let token: string | undefined;
+    if (typeof authHeader === "string" && authHeader.startsWith("Bearer ")) {
+      token = authHeader.slice("Bearer ".length).trim();
+    }
+
+    const cookies = this.parseCookies(req.headers.cookie);
+    const sessionCookie = token || cookies.get(COOKIE_NAME);
+    const session = await this.verifySession(sessionCookie);
+
+    if (!session) {
+      throw ForbiddenError("Invalid session cookie");
+    }
+
+    const sessionUserId = session.openId;
+    const signedInAt = new Date();
+    let user = await db.getUserByOpenId(sessionUserId);
+
+    // If user not in DB, sync from OAuth server automatically
+    if (!user) {
+      try {
+        const userInfo = await this.getUserInfoWithJwt(sessionCookie ?? "");
+        await db.upsertUser({
+          openId: userInfo.openId,
+          name: userInfo.name || null,
+          email: userInfo.email ?? null,
+          loginMethod: userInfo.loginMethod ?? userInfo.platform ?? null,
+          lastSignedIn: signedInAt,
+        });
+        user = await db.getUserByOpenId(userInfo.openId);
+      } catch (error) {
+        console.error("[Auth] Failed to sync user from OAuth:", error);
+        throw ForbiddenError("Failed to sync user info");
+      }
+    }
+
+    if (!user) {
+      throw ForbiddenError("User not found");
+    }
+
+    await db.upsertUser({
+      openId: user.openId,
+      lastSignedIn: signedInAt,
+    });
+
+    return user;
+  }
+}
+
+export const sdk = new SDKServer();

server/_core/systemRouter.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import { notifyOwner } from "./notification";
+import { adminProcedure, publicProcedure, router } from "./trpc";
+
+export const systemRouter = router({
+  health: publicProcedure
+    .input(
+      z.object({
+        timestamp: z.number().min(0, "timestamp cannot be negative"),
+      }),
+    )
+    .query(() => ({
+      ok: true,
+    })),
+
+  notifyOwner: adminProcedure
+    .input(
+      z.object({
+        title: z.string().min(1, "title is required"),
+        content: z.string().min(1, "content is required"),
+      }),
+    )
+    .mutation(async ({ input }) => {
+      const delivered = await notifyOwner(input);
+      return {
+        success: delivered,
+      } as const;
+    }),
+});

server/_core/trpc.ts

@@ -0,0 +1,45 @@
+import { NOT_ADMIN_ERR_MSG, UNAUTHED_ERR_MSG } from "../../shared/const.js";
+import { initTRPC, TRPCError } from "@trpc/server";
+import superjson from "superjson";
+import type { TrpcContext } from "./context";
+
+const t = initTRPC.context<TrpcContext>().create({
+  transformer: superjson,
+});
+
+export const router = t.router;
+export const publicProcedure = t.procedure;
+
+const requireUser = t.middleware(async (opts) => {
+  const { ctx, next } = opts;
+
+  if (!ctx.user) {
+    throw new TRPCError({ code: "UNAUTHORIZED", message: UNAUTHED_ERR_MSG });
+  }
+
+  return next({
+    ctx: {
+      ...ctx,
+      user: ctx.user,
+    },
+  });
+});
+
+export const protectedProcedure = t.procedure.use(requireUser);
+
+export const adminProcedure = t.procedure.use(
+  t.middleware(async (opts) => {
+    const { ctx, next } = opts;
+
+    if (!ctx.user || ctx.user.role !== "admin") {
+      throw new TRPCError({ code: "FORBIDDEN", message: NOT_ADMIN_ERR_MSG });
+    }
+
+    return next({
+      ctx: {
+        ...ctx,
+        user: ctx.user,
+      },
+    });
+  }),
+);

server/_core/types/cookie.d.ts

@@ -0,0 +1,3 @@
+declare module "cookie" {
+  export function parse(str: string, options?: Record<string, unknown>): Record<string, string>;
+}

server/_core/types/manusTypes.ts

@@ -0,0 +1,69 @@
+// WebDev Auth TypeScript types
+// Auto-generated from protobuf definitions
+// Generated on: 2025-09-24T05:57:57.338Z
+
+export interface AuthorizeRequest {
+  redirectUri: string;
+  projectId: string;
+  state: string;
+  responseType: string;
+  scope: string;
+}
+
+export interface AuthorizeResponse {
+  redirectUrl: string;
+}
+
+export interface ExchangeTokenRequest {
+  grantType: string;
+  code: string;
+  refreshToken?: string;
+  clientId: string;
+  clientSecret?: string;
+  redirectUri: string;
+}
+
+export interface ExchangeTokenResponse {
+  accessToken: string;
+  tokenType: string;
+  expiresIn: number;
+  refreshToken?: string;
+  scope: string;
+  idToken: string;
+}
+
+export interface GetUserInfoRequest {
+  accessToken: string;
+}
+
+export interface GetUserInfoResponse {
+  openId: string;
+  projectId: string;
+  name: string;
+  email?: string | null;
+  platform?: string | null;
+  loginMethod?: string | null;
+}
+
+export interface CanAccessRequest {
+  openId: string;
+  projectId: string;
+}
+
+export interface CanAccessResponse {
+  canAccess: boolean;
+}
+
+export interface GetUserInfoWithJwtRequest {
+  jwtToken: string;
+  projectId: string;
+}
+
+export interface GetUserInfoWithJwtResponse {
+  openId: string;
+  projectId: string;
+  name: string;
+  email?: string | null;
+  platform?: string | null;
+  loginMethod?: string | null;
+}

server/_core/voiceTranscription.ts

@@ -0,0 +1,283 @@
+/**
+ * Voice transcription helper using internal Speech-to-Text service
+ *
+ * Frontend implementation guide:
+ * 1. Capture audio using MediaRecorder API
+ * 2. Upload audio to storage (e.g., S3) to get URL
+ * 3. Call transcription with the URL
+ *
+ * Example usage:
+ * ```tsx
+ * // Frontend component
+ * const transcribeMutation = trpc.voice.transcribe.useMutation({
+ *   onSuccess: (data) => {
+ *     console.log(data.text); // Full transcription
+ *     console.log(data.language); // Detected language
+ *     console.log(data.segments); // Timestamped segments
+ *   }
+ * });
+ *
+ * // After uploading audio to storage
+ * transcribeMutation.mutate({
+ *   audioUrl: uploadedAudioUrl,
+ *   language: 'en', // optional
+ *   prompt: 'Transcribe the meeting' // optional
+ * });
+ * ```
+ */
+import { ENV } from "./env";
+
+export type TranscribeOptions = {
+  audioUrl: string; // URL to the audio file (e.g., S3 URL)
+  language?: string; // Optional: specify language code (e.g., "en", "es", "zh")
+  prompt?: string; // Optional: custom prompt for the transcription
+};
+
+// Native Whisper API segment format
+export type WhisperSegment = {
+  id: number;
+  seek: number;
+  start: number;
+  end: number;
+  text: string;
+  tokens: number[];
+  temperature: number;
+  avg_logprob: number;
+  compression_ratio: number;
+  no_speech_prob: number;
+};
+
+// Native Whisper API response format
+export type WhisperResponse = {
+  task: "transcribe";
+  language: string;
+  duration: number;
+  text: string;
+  segments: WhisperSegment[];
+};
+
+export type TranscriptionResponse = WhisperResponse; // Return native Whisper API response directly
+
+export type TranscriptionError = {
+  error: string;
+  code:
+    | "FILE_TOO_LARGE"
+    | "INVALID_FORMAT"
+    | "TRANSCRIPTION_FAILED"
+    | "UPLOAD_FAILED"
+    | "SERVICE_ERROR";
+  details?: string;
+};
+
+/**
+ * Transcribe audio to text using the internal Speech-to-Text service
+ *
+ * @param options - Audio data and metadata
+ * @returns Transcription result or error
+ */
+export async function transcribeAudio(
+  options: TranscribeOptions,
+): Promise<TranscriptionResponse | TranscriptionError> {
+  try {
+    // Step 1: Validate environment configuration
+    if (!ENV.forgeApiUrl) {
+      return {
+        error: "Voice transcription service is not configured",
+        code: "SERVICE_ERROR",
+        details: "BUILT_IN_FORGE_API_URL is not set",
+      };
+    }
+    if (!ENV.forgeApiKey) {
+      return {
+        error: "Voice transcription service authentication is missing",
+        code: "SERVICE_ERROR",
+        details: "BUILT_IN_FORGE_API_KEY is not set",
+      };
+    }
+
+    // Step 2: Download audio from URL
+    let audioBuffer: Buffer;
+    let mimeType: string;
+    try {
+      const response = await fetch(options.audioUrl);
+      if (!response.ok) {
+        return {
+          error: "Failed to download audio file",
+          code: "INVALID_FORMAT",
+          details: `HTTP ${response.status}: ${response.statusText}`,
+        };
+      }
+
+      audioBuffer = Buffer.from(await response.arrayBuffer());
+      mimeType = response.headers.get("content-type") || "audio/mpeg";
+
+      // Check file size (16MB limit)
+      const sizeMB = audioBuffer.length / (1024 * 1024);
+      if (sizeMB > 16) {
+        return {
+          error: "Audio file exceeds maximum size limit",
+          code: "FILE_TOO_LARGE",
+          details: `File size is ${sizeMB.toFixed(2)}MB, maximum allowed is 16MB`,
+        };
+      }
+    } catch (error) {
+      return {
+        error: "Failed to fetch audio file",
+        code: "SERVICE_ERROR",
+        details: error instanceof Error ? error.message : "Unknown error",
+      };
+    }
+
+    // Step 3: Create FormData for multipart upload to Whisper API
+    const formData = new FormData();
+
+    // Create a Blob from the buffer and append to form
+    const filename = `audio.${getFileExtension(mimeType)}`;
+    const audioBlob = new Blob([new Uint8Array(audioBuffer)], { type: mimeType });
+    formData.append("file", audioBlob, filename);
+
+    formData.append("model", "whisper-1");
+    formData.append("response_format", "verbose_json");
+
+    // Add prompt - use custom prompt if provided, otherwise generate based on language
+    const prompt =
+      options.prompt ||
+      (options.language
+        ? `Transcribe the user's voice to text, the user's working language is ${getLanguageName(options.language)}`
+        : "Transcribe the user's voice to text");
+    formData.append("prompt", prompt);
+
+    // Step 4: Call the transcription service
+    const baseUrl = ENV.forgeApiUrl.endsWith("/") ? ENV.forgeApiUrl : `${ENV.forgeApiUrl}/`;
+
+    const fullUrl = new URL("v1/audio/transcriptions", baseUrl).toString();
+
+    const response = await fetch(fullUrl, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${ENV.forgeApiKey}`,
+        "Accept-Encoding": "identity",
+      },
+      body: formData,
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text().catch(() => "");
+      return {
+        error: "Transcription service request failed",
+        code: "TRANSCRIPTION_FAILED",
+        details: `${response.status} ${response.statusText}${errorText ? `: ${errorText}` : ""}`,
+      };
+    }
+
+    // Step 5: Parse and return the transcription result
+    const whisperResponse = (await response.json()) as WhisperResponse;
+
+    // Validate response structure
+    if (!whisperResponse.text || typeof whisperResponse.text !== "string") {
+      return {
+        error: "Invalid transcription response",
+        code: "SERVICE_ERROR",
+        details: "Transcription service returned an invalid response format",
+      };
+    }
+
+    return whisperResponse; // Return native Whisper API response directly
+  } catch (error) {
+    // Handle unexpected errors
+    return {
+      error: "Voice transcription failed",
+      code: "SERVICE_ERROR",
+      details: error instanceof Error ? error.message : "An unexpected error occurred",
+    };
+  }
+}
+
+/**
+ * Helper function to get file extension from MIME type
+ */
+function getFileExtension(mimeType: string): string {
+  const mimeToExt: Record<string, string> = {
+    "audio/webm": "webm",
+    "audio/mp3": "mp3",
+    "audio/mpeg": "mp3",
+    "audio/wav": "wav",
+    "audio/wave": "wav",
+    "audio/ogg": "ogg",
+    "audio/m4a": "m4a",
+    "audio/mp4": "m4a",
+  };
+
+  return mimeToExt[mimeType] || "audio";
+}
+
+/**
+ * Helper function to get full language name from ISO code
+ */
+function getLanguageName(langCode: string): string {
+  const langMap: Record<string, string> = {
+    en: "English",
+    es: "Spanish",
+    fr: "French",
+    de: "German",
+    it: "Italian",
+    pt: "Portuguese",
+    ru: "Russian",
+    ja: "Japanese",
+    ko: "Korean",
+    zh: "Chinese",
+    ar: "Arabic",
+    hi: "Hindi",
+    nl: "Dutch",
+    pl: "Polish",
+    tr: "Turkish",
+    sv: "Swedish",
+    da: "Danish",
+    no: "Norwegian",
+    fi: "Finnish",
+  };
+
+  return langMap[langCode] || langCode;
+}
+
+/**
+ * Example tRPC procedure implementation:
+ *
+ * ```ts
+ * // In server/routers.ts
+ * import { transcribeAudio } from "./_core/voiceTranscription";
+ *
+ * export const voiceRouter = router({
+ *   transcribe: protectedProcedure
+ *     .input(z.object({
+ *       audioUrl: z.string(),
+ *       language: z.string().optional(),
+ *       prompt: z.string().optional(),
+ *     }))
+ *     .mutation(async ({ input, ctx }) => {
+ *       const result = await transcribeAudio(input);
+ *
+ *       // Check if it's an error
+ *       if ('error' in result) {
+ *         throw new TRPCError({
+ *           code: 'BAD_REQUEST',
+ *           message: result.error,
+ *           cause: result,
+ *         });
+ *       }
+ *
+ *       // Optionally save transcription to database
+ *       await db.insert(transcriptions).values({
+ *         userId: ctx.user.id,
+ *         text: result.text,
+ *         duration: result.duration,
+ *         language: result.language,
+ *         audioUrl: input.audioUrl,
+ *         createdAt: new Date(),
+ *       });
+ *
+ *       return result;
+ *     }),
+ * });
+ * ```
+ */

server/db.ts

@@ -0,0 +1,92 @@
+import { eq } from "drizzle-orm";
+import { drizzle } from "drizzle-orm/mysql2";
+import { InsertUser, users } from "../drizzle/schema";
+import { ENV } from "./_core/env";
+
+let _db: ReturnType<typeof drizzle> | null = null;
+
+// Lazily create the drizzle instance so local tooling can run without a DB.
+export async function getDb() {
+  if (!_db && process.env.DATABASE_URL) {
+    try {
+      _db = drizzle(process.env.DATABASE_URL);
+    } catch (error) {
+      console.warn("[Database] Failed to connect:", error);
+      _db = null;
+    }
+  }
+  return _db;
+}
+
+export async function upsertUser(user: InsertUser): Promise<void> {
+  if (!user.openId) {
+    throw new Error("User openId is required for upsert");
+  }
+
+  const db = await getDb();
+  if (!db) {
+    console.warn("[Database] Cannot upsert user: database not available");
+    return;
+  }
+
+  try {
+    const values: InsertUser = {
+      openId: user.openId,
+    };
+    const updateSet: Record<string, unknown> = {};
+
+    const textFields = ["name", "email", "loginMethod"] as const;
+    type TextField = (typeof textFields)[number];
+
+    const assignNullable = (field: TextField) => {
+      const value = user[field];
+      if (value === undefined) return;
+      const normalized = value ?? null;
+      values[field] = normalized;
+      updateSet[field] = normalized;
+    };
+
+    textFields.forEach(assignNullable);
+
+    if (user.lastSignedIn !== undefined) {
+      values.lastSignedIn = user.lastSignedIn;
+      updateSet.lastSignedIn = user.lastSignedIn;
+    }
+    if (user.role !== undefined) {
+      values.role = user.role;
+      updateSet.role = user.role;
+    } else if (user.openId === ENV.ownerOpenId) {
+      values.role = "admin";
+      updateSet.role = "admin";
+    }
+
+    if (!values.lastSignedIn) {
+      values.lastSignedIn = new Date();
+    }
+
+    if (Object.keys(updateSet).length === 0) {
+      updateSet.lastSignedIn = new Date();
+    }
+
+    await db.insert(users).values(values).onDuplicateKeyUpdate({
+      set: updateSet,
+    });
+  } catch (error) {
+    console.error("[Database] Failed to upsert user:", error);
+    throw error;
+  }
+}
+
+export async function getUserByOpenId(openId: string) {
+  const db = await getDb();
+  if (!db) {
+    console.warn("[Database] Cannot get user: database not available");
+    return undefined;
+  }
+
+  const result = await db.select().from(users).where(eq(users.openId, openId)).limit(1);
+
+  return result.length > 0 ? result[0] : undefined;
+}
+
+// TODO: add feature queries here as your schema grows.

server/routers.ts

@@ -0,0 +1,68 @@
+import { z } from "zod";
+import { COOKIE_NAME } from "../shared/const.js";
+import { getSessionCookieOptions } from "./_core/cookies";
+import { systemRouter } from "./_core/systemRouter";
+import { publicProcedure, router } from "./_core/trpc";
+import { transcribeAudio } from "./_core/voiceTranscription";
+import { storagePut } from "./storage";
+
+export const appRouter = router({
+  system: systemRouter,
+  auth: router({
+    me: publicProcedure.query((opts) => opts.ctx.user),
+    logout: publicProcedure.mutation(({ ctx }) => {
+      const cookieOptions = getSessionCookieOptions(ctx.req);
+      ctx.res.clearCookie(COOKIE_NAME, { ...cookieOptions, maxAge: -1 });
+      return { success: true } as const;
+    }),
+  }),
+
+  voice: router({
+    /**
+     * يستقبل ملف صوتي مُرمَّز بـ Base64، يرفعه إلى S3، ثم يُرسله لـ Whisper للتعرف على الكلام العربي
+     */
+    transcribe: publicProcedure
+      .input(
+        z.object({
+          audioBase64: z.string(), // ملف الصوت مُرمَّز بـ base64
+          mimeType: z.string().default("audio/m4a"), // نوع الملف
+          language: z.string().default("ar"), // اللغة (ar للعربية)
+        })
+      )
+      .mutation(async ({ input }) => {
+        // 1. تحويل base64 إلى Buffer
+        const audioBuffer = Buffer.from(input.audioBase64, "base64");
+
+        // 2. رفع الملف إلى S3 بمفتاح عشوائي
+        const suffix = Date.now().toString(36);
+        const ext = input.mimeType.split("/")[1]?.split(";")[0] ?? "m4a";
+        const fileKey = `voice-recordings/rec-${suffix}.${ext}`;
+
+        const { url: audioUrl } = await storagePut(
+          fileKey,
+          audioBuffer,
+          input.mimeType
+        );
+
+        // 3. إرسال الرابط لـ Whisper مع تحديد اللغة العربية
+        const result = await transcribeAudio({
+          audioUrl,
+          language: input.language,
+          prompt: "هذا تسجيل صوتي باللغة العربية",
+        });
+
+        // التحقق من نوع النتيجة (نجاح أو خطأ)
+        if ("error" in result) {
+          throw new Error(result.details ?? result.error);
+        }
+
+        return {
+          text: result.text ?? "",
+          language: result.language ?? input.language,
+          segments: result.segments ?? [],
+        };
+      }),
+  }),
+});
+
+export type AppRouter = typeof appRouter;

server/storage.ts

@@ -0,0 +1,95 @@
+// Preconfigured storage helpers for Manus WebDev templates
+// Uses the Biz-provided storage proxy (Authorization: Bearer <token>)
+
+import { ENV } from "./_core/env";
+
+type StorageConfig = { baseUrl: string; apiKey: string };
+
+function getStorageConfig(): StorageConfig {
+  const baseUrl = ENV.forgeApiUrl;
+  const apiKey = ENV.forgeApiKey;
+
+  if (!baseUrl || !apiKey) {
+    throw new Error(
+      "Storage proxy credentials missing: set BUILT_IN_FORGE_API_URL and BUILT_IN_FORGE_API_KEY",
+    );
+  }
+
+  return { baseUrl: baseUrl.replace(/\/+$/, ""), apiKey };
+}
+
+function buildUploadUrl(baseUrl: string, relKey: string): URL {
+  const url = new URL("v1/storage/upload", ensureTrailingSlash(baseUrl));
+  url.searchParams.set("path", normalizeKey(relKey));
+  return url;
+}
+
+async function buildDownloadUrl(baseUrl: string, relKey: string, apiKey: string): Promise<string> {
+  const downloadApiUrl = new URL("v1/storage/downloadUrl", ensureTrailingSlash(baseUrl));
+  downloadApiUrl.searchParams.set("path", normalizeKey(relKey));
+  const response = await fetch(downloadApiUrl, {
+    method: "GET",
+    headers: buildAuthHeaders(apiKey),
+  });
+  return (await response.json()).url;
+}
+
+function ensureTrailingSlash(value: string): string {
+  return value.endsWith("/") ? value : `${value}/`;
+}
+
+function normalizeKey(relKey: string): string {
+  return relKey.replace(/^\/+/, "");
+}
+
+function toFormData(
+  data: Buffer | Uint8Array | string,
+  contentType: string,
+  fileName: string,
+): FormData {
+  const blob =
+    typeof data === "string"
+      ? new Blob([data], { type: contentType })
+      : new Blob([data as any], { type: contentType });
+  const form = new FormData();
+  form.append("file", blob, fileName || "file");
+  return form;
+}
+
+function buildAuthHeaders(apiKey: string): HeadersInit {
+  return { Authorization: `Bearer ${apiKey}` };
+}
+
+export async function storagePut(
+  relKey: string,
+  data: Buffer | Uint8Array | string,
+  contentType = "application/octet-stream",
+): Promise<{ key: string; url: string }> {
+  const { baseUrl, apiKey } = getStorageConfig();
+  const key = normalizeKey(relKey);
+  const uploadUrl = buildUploadUrl(baseUrl, key);
+  const formData = toFormData(data, contentType, key.split("/").pop() ?? key);
+  const response = await fetch(uploadUrl, {
+    method: "POST",
+    headers: buildAuthHeaders(apiKey),
+    body: formData,
+  });
+
+  if (!response.ok) {
+    const message = await response.text().catch(() => response.statusText);
+    throw new Error(
+      `Storage upload failed (${response.status} ${response.statusText}): ${message}`,
+    );
+  }
+  const url = (await response.json()).url;
+  return { key, url };
+}
+
+export async function storageGet(relKey: string): Promise<{ key: string; url: string }> {
+  const { baseUrl, apiKey } = getStorageConfig();
+  const key = normalizeKey(relKey);
+  return {
+    key,
+    url: await buildDownloadUrl(baseUrl, key, apiKey),
+  };
+}

server/voice-ws.ts

@@ -0,0 +1,810 @@
+/**
+ * voice-ws.ts — Real-time voice-to-sign WebSocket server
+ *
+ * Protocol (client → server):
+ *   { type: "chunk", audio: "<base64>", mimeType: "audio/m4a", chunkId: N }
+ *   { type: "text",  text: "...",       chunkId: N }   ← legacy: pre-recognized text
+ *   { type: "stop" }
+ *
+ * Protocol (server → client):
+ *   { type: "ready" }
+ *   { type: "queued",             chunkId, queueSize }
+ *   { type: "partial_transcript", text, chunkId }
+ *   { type: "final_transcript",   text, words, chunkId, rawText }
+ *   { type: "words",              words, chunkId, rawText }  ← legacy compat
+ *   { type: "error",              message, chunkId? }
+ *
+ * Algorithms:
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 1. SLIDING WINDOW CONTEXT (NLP)
+ *    Each chunk sent to Whisper includes the last 5 words as prompt context
+ *    to prevent word splitting across chunk boundaries.
+ *
+ * 2. MIN-HEAP ORDERED DELIVERY (Data Structure)
+ *    Results stored in a min-heap sorted by chunkId for ordered delivery
+ *    even when results arrive out of order.
+ *
+ * 3. MAXIMUM MUNCH TOKENIZATION (NLP)
+ *    Extract all known words from a sentence using greedy longest-match-first.
+ *
+ * 4. PARALLEL PROCESSING + DROP STRATEGY (Performance)
+ *    Process up to 4 chunks in parallel; drop excess to prevent queue buildup.
+ *
+ * 5. ARABIC TEXT NORMALIZATION (NLP) — internal only
+ *    Used only for sign/avatar VOCAB matching. Raw dialect preserved in transcripts.
+ *
+ * 6. POSITION-BASED DEDUPLICATION
+ *    Track sent words by position to prevent immediate repeats.
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+
+import { WebSocketServer, WebSocket } from "ws";
+import type { Server } from "http";
+import { ENV } from "./_core/env";
+
+// ─── Message types ───────────────────────────────────────────────────────────
+
+interface ChunkMsg {
+  type: "chunk";
+  audio: string; // base64
+  mimeType?: string;
+  chunkId: number;
+}
+interface TextMsg {
+  type: "text";
+  text: string;
+  chunkId: number;
+}
+interface StopMsg {
+  type: "stop";
+}
+type ClientMessage = ChunkMsg | TextMsg | StopMsg;
+
+// ─── Arabic text normalization (internal only — for sign/avatar matching) ────
+
+/** Normalize for VOCAB lookup only. Never use on user-facing transcript text. */
+function normalizeAr(s: string): string {
+  return s
+    .replace(/[\u064B-\u065F\u0670]/g, "") // remove diacritics
+    .replace(/[أإآ]/g, "ا") // unify alif
+    .replace(/ة/g, "ه") // taa marbuta → haa
+    .replace(/ى/g, "ي") // alif maqsura → yaa
+    .replace(/[^\u0600-\u06FF\s]/g, " ") // remove non-Arabic
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+// ─── Vocabulary (normalized → canonical key) ─────────────────────────────────
+
+const VOCAB: Record<string, string> = {
+  انا: "أنا",
+  بحب: "بحب",
+  احب: "بحب",
+  اهواك: "بحب",
+  صباح: "صباح",
+  الخير: "الخير",
+  خير: "الخير",
+  النور: "النور",
+  نور: "النور",
+  المدرسه: "المدرسة",
+  مدرسه: "المدرسة",
+  مدرسة: "المدرسة",
+  التعليم: "المدرسة",
+  الدراسه: "المدرسة",
+  الدراسة: "المدرسة",
+  عشان: "عشان",
+  لان: "عشان",
+  لأن: "عشان",
+  مرحبا: "مرحبا",
+  مرحبه: "مرحبا",
+  اهلا: "مرحبا",
+  هلا: "مرحبا",
+  السلام: "مرحبا",
+  اهلن: "مرحبا",
+  شكرا: "شكراً",
+  شكر: "شكراً",
+  شكرًا: "شكراً",
+  عفوا: "عفواً",
+  عفو: "عفواً",
+  مساء: "مساء",
+  مساءً: "مساء",
+  مساعده: "مساعدة",
+  ساعدني: "مساعدة",
+  نجده: "مساعدة",
+  مساعدة: "مساعدة",
+  النجده: "مساعدة",
+  نعم: "نعم",
+  اه: "نعم",
+  اي: "نعم",
+  صح: "نعم",
+  ايوه: "نعم",
+  لا: "لا",
+  ماء: "ماء",
+  ميه: "ماء",
+  مي: "ماء",
+  ماي: "ماء",
+  ماءً: "ماء",
+  طيب: "طيب",
+  حسنا: "طيب",
+  تمام: "طيب",
+  حسنًا: "طيب",
+  اوكيه: "طيب",
+  سعيد: "سعيد",
+  مبسوط: "سعيد",
+  فرحان: "سعيد",
+  سعيده: "سعيد",
+  مبسوطه: "سعيد",
+};
+
+/**
+ * NLP: Extract all known words from a sentence in order.
+ * Algorithm: Maximum Munch on single-word tokens.
+ */
+function extractAllWords(rawText: string): string[] {
+  const normalized = normalizeAr(rawText);
+  const tokens = normalized.split(/\s+/).filter(Boolean);
+  const result: string[] = [];
+  for (const token of tokens) {
+    const canonical = VOCAB[token];
+    if (canonical) result.push(canonical);
+  }
+  return result;
+}
+
+// ─── Min-Heap for ordered delivery ───────────────────────────────────────────
+
+interface HeapItem {
+  chunkId: number;
+  words: string[];
+  rawText: string;
+}
+
+class MinHeap {
+  private data: HeapItem[] = [];
+  push(item: HeapItem) {
+    this.data.push(item);
+    this.bubbleUp(this.data.length - 1);
+  }
+  peek(): HeapItem | undefined {
+    return this.data[0];
+  }
+  pop(): HeapItem | undefined {
+    if (!this.data.length) return undefined;
+    const top = this.data[0];
+    const last = this.data.pop()!;
+    if (this.data.length) {
+      this.data[0] = last;
+      this.sinkDown(0);
+    }
+    return top;
+  }
+  get size() {
+    return this.data.length;
+  }
+  private bubbleUp(i: number) {
+    while (i > 0) {
+      const p = (i - 1) >> 1;
+      if (this.data[p].chunkId <= this.data[i].chunkId) break;
+      [this.data[p], this.data[i]] = [this.data[i], this.data[p]];
+      i = p;
+    }
+  }
+  private sinkDown(i: number) {
+    const n = this.data.length;
+    while (true) {
+      let min = i;
+      const l = 2 * i + 1,
+        r = 2 * i + 2;
+      if (l < n && this.data[l].chunkId < this.data[min].chunkId) min = l;
+      if (r < n && this.data[r].chunkId < this.data[min].chunkId) min = r;
+      if (min === i) break;
+      [this.data[min], this.data[i]] = [this.data[i], this.data[min]];
+      i = min;
+    }
+  }
+}
+
+// ─── Sliding Window Context ──────────────────────────────────────────────────
+
+class SlidingContext {
+  private lastRawWords: string[] = [];
+
+  getPrompt(): string {
+    // Whisper's initial_prompt is designed for *prior speech context only* — NOT
+    // instructions. Passing Arabic instructions causes Whisper to echo their
+    // vocabulary (e.g. "موسيقى") as hallucinations. Only pass the last spoken
+    // words so Whisper maintains continuity across chunk boundaries.
+    if (!this.lastRawWords.length) return "";
+    return this.lastRawWords.slice(-5).join(" ");
+  }
+
+  /** Feed raw (un-normalized) Whisper output to preserve dialect in context */
+  update(rawText: string) {
+    const words = rawText.trim().split(/\s+/).filter(Boolean);
+    this.lastRawWords = [...this.lastRawWords, ...words].slice(-10);
+  }
+
+  reset() {
+    this.lastRawWords = [];
+  }
+}
+
+// ─── Voice Session ───────────────────────────────────────────────────────────
+
+class VoiceSession {
+  private heap = new MinHeap();
+  private nextExpected = 0;
+  private processing = 0;
+  private readonly MAX_CONCURRENT = 4;
+  private backlog: {
+    chunkId: number;
+    audioBase64: string;
+    mimeType: string;
+    ext: string;
+  }[] = [];
+  private context = new SlidingContext();
+  private allSentWords: string[] = [];
+  private totalEnqueued = 0;
+  /** How many consecutive chunks came back empty (silence/hallucination filtered) */
+  private consecutiveSilenceCount = 0;
+
+  constructor(
+    private ws: WebSocket,
+    private sendMsg: (msg: Record<string, any>) => void,
+  ) {}
+
+  enqueue(chunk: {
+    chunkId: number;
+    audioBase64: string;
+    mimeType: string;
+    ext: string;
+  }) {
+    this.totalEnqueued++;
+    this.backlog.push(chunk);
+    this.sendMsg({
+      type: "queued",
+      chunkId: chunk.chunkId,
+      queueSize: this.processing + this.backlog.length,
+    });
+
+    this.drainBacklog();
+  }
+
+  private drainBacklog() {
+    while (this.processing < this.MAX_CONCURRENT && this.backlog.length > 0) {
+      const chunk = this.backlog.shift()!;
+      this.processing++;
+      const prompt = this.context.getPrompt();
+      this.processChunk(chunk, prompt)
+        .catch((err) =>
+          console.error(`[voice-ws] chunk ${chunk.chunkId}:`, err.message),
+        )
+        .finally(() => {
+          this.processing--;
+          this.drainBacklog();
+        });
+    }
+  }
+
+  private async processChunk(
+    chunk: {
+      chunkId: number;
+      audioBase64: string;
+      mimeType: string;
+      ext: string;
+    },
+    prompt: string,
+  ) {
+    let text: string;
+    try {
+      text = await transcribeWithWhisper(
+        chunk.audioBase64,
+        chunk.ext,
+        chunk.mimeType,
+        prompt,
+      );
+    } catch (err: any) {
+      console.error(
+        `[voice-ws] ❌ transcription failed for chunk ${chunk.chunkId}:`,
+        err.message,
+      );
+      this.sendMsg({
+        type: "error",
+        message: `Transcription failed: ${err.message}`,
+        chunkId: chunk.chunkId,
+      });
+      // Still add to heap with empty text so ordering isn't broken
+      text = "";
+    }
+
+    // Only update context on real speech.
+    // On silence/hallucination (text === ""), increment the silence streak.
+    // After 2+ consecutive silent chunks reset the context so stale speech
+    // content stops "anchoring" Whisper and pulling it toward hallucinations.
+    if (text) {
+      this.consecutiveSilenceCount = 0;
+      this.context.update(text);
+    } else {
+      this.consecutiveSilenceCount++;
+      if (this.consecutiveSilenceCount >= 1) {
+        this.context.reset();
+        console.log("[voice-ws] 🔄 context reset — silence detected");
+      }
+    }
+
+    // Send partial transcript immediately (before word extraction + ordering)
+    if (text.trim()) {
+      this.sendMsg({
+        type: "partial_transcript",
+        text: text.trim(),
+        chunkId: chunk.chunkId,
+      });
+    }
+
+    const words = extractAllWords(text);
+    this.heap.push({ chunkId: chunk.chunkId, words, rawText: text });
+    this.flushOrdered();
+  }
+
+  private flushOrdered() {
+    while (
+      this.heap.size > 0 &&
+      this.heap.peek()!.chunkId === this.nextExpected
+    ) {
+      const item = this.heap.pop()!;
+      this.nextExpected++;
+
+      // Deduplicate words by position
+      const newWords: string[] = [];
+      if (item.words.length > 0) {
+        for (const w of item.words) {
+          if (this.shouldSend(w)) {
+            newWords.push(w);
+            this.allSentWords.push(w);
+          }
+        }
+      }
+
+      // Send final_transcript with both text and matched words
+      this.sendMsg({
+        type: "final_transcript",
+        text: item.rawText.trim(),
+        words: newWords,
+        chunkId: item.chunkId,
+        rawText: item.rawText.trim(),
+      });
+
+      // Also send legacy "words" message for backward compatibility
+      if (newWords.length > 0) {
+        this.sendMsg({
+          type: "words",
+          words: newWords,
+          chunkId: item.chunkId,
+          rawText: item.rawText,
+        });
+      }
+    }
+  }
+
+  /**
+   * Should we send this word?
+   * Yes if: never sent before, or 8+ other words have been sent since.
+   */
+  private shouldSend(word: string): boolean {
+    const lastIdx = this.allSentWords.lastIndexOf(word);
+    if (lastIdx === -1) return true;
+    return this.allSentWords.length - lastIdx > 8;
+  }
+
+  /** Process pre-recognized text (from Web Speech API) — no Whisper needed */
+  processText(chunkId: number, rawText: string) {
+    if (!rawText.trim()) return;
+    this.totalEnqueued++;
+    this.sendMsg({
+      type: "queued",
+      chunkId,
+      queueSize: this.processing,
+    });
+
+    const words = extractAllWords(rawText);
+    this.context.update(rawText);
+    this.heap.push({ chunkId, words, rawText });
+    this.flushOrdered();
+  }
+
+  reset() {
+    this.heap = new MinHeap();
+    this.nextExpected = 0;
+    this.processing = 0;
+    this.context.reset();
+    this.allSentWords = [];
+    this.totalEnqueued = 0;
+    this.consecutiveSilenceCount = 0;
+  }
+}
+
+// ─── Whisper API ─────────────────────────────────────────────────────────────
+
+// ─── Silence / hallucination detection ───────────────────────────────────────
+
+/** no_speech_prob threshold: above this → treat chunk as silence.
+ *  0.6 is well-calibrated for Arabic speech; 0.35 was too aggressive and
+ *  caused real speech with low energy to be silently dropped. */
+const NO_SPEECH_THRESHOLD = 0.6;
+
+/** avg_logprob threshold: below this → model is guessing, not transcribing.
+ *  -0.8 avoids over-filtering dialect Arabic which naturally scores lower. */
+const LOW_CONFIDENCE_LOGPROB = -0.8;
+
+/** compression_ratio threshold: above this → repetitive/looping hallucination */
+const HIGH_COMPRESSION_RATIO = 2.4;
+
+/**
+ * Punctuation-only / symbol-only outputs that carry no speech content.
+ */
+const HALLUCINATION_RE = /^[\s.،؟!…\-–—\u200B-\u200F♪♫♬]+$/;
+
+/**
+ * Ghost phrases Whisper hallucinates from YouTube/podcast training data.
+ * These are STRIPPED from transcripts (not used to drop the whole chunk),
+ * so real speech appearing in the same chunk is preserved.
+ *
+ * Order matters: longer/more-specific phrases must come before their substrings
+ * so the longer form is stripped first.
+ */
+const GHOST_PHRASES: string[] = [
+  // ── Arabic — longer phrases first ────────────────────────────────────────
+  "شكراً على المشاهدة",
+  "شكرا على المشاهدة",
+  "شكراً على المتابعة",
+  "شكرا على المتابعة",
+  "للمزيد من الفيديوهات",
+  "للمزيد من المحتوى",
+  "لا تنسى الاشتراك",
+  "لا تنسوا الاشتراك",
+  "اشترك معنا",
+  "اللهم صل على محمد",
+  "صلى الله عليه وسلم",
+  "بسم الله الرحمن الرحيم",
+  "الحمد لله رب العالمين",
+  // ── Arabic — single-word ghosts ───────────────────────────────────────────
+  "اشتركوا", // subscribe (plural)  — before "اشترك"
+  "أشترك", // subscribe (hamza)
+  "اشترك", // subscribe
+  "الحمد لله",
+  "سبحان الله",
+  "موسيقى", // music — most common Arabic hallucination on silence
+  "موسيقا",
+  // ── English (training bleed) ─────────────────────────────────────────────
+  "thanks for watching",
+  "thank you for watching",
+  "please subscribe",
+  "see you next time",
+  "background music",
+  "[applause]",
+  "[laughter]",
+  "[silence]",
+  "[inaudible]",
+  "[music]",
+  "subscribe",
+  "music",
+];
+
+/**
+ * Strip every ghost phrase from `text`, normalise whitespace, and return
+ * the cleaned string.  Returns "" if nothing real remains.
+ *
+ * Stripping (not dropping) preserves real speech that appeared in the same
+ * chunk as a hallucination — the previous approach discarded whole chunks.
+ */
+function stripGhostPhrases(text: string): string {
+  let result = text.trim();
+  for (const ghost of GHOST_PHRASES) {
+    // Arabic has no case, but toLowerCase is harmless and handles English ghosts.
+    const re = new RegExp(ghost.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "gi");
+    const before = result;
+    result = result
+      .replace(re, " ")
+      .replace(/\s{2,}/g, " ")
+      .trim();
+    if (result !== before) {
+      console.log(`[voice-ws] ✂️ stripped ghost "${ghost}" → "${result}"`);
+    }
+  }
+  if (!result || HALLUCINATION_RE.test(result)) return "";
+  return result;
+}
+
+/**
+ * Segment-level stats check: returns true only when the ENTIRE chunk has
+ * no real speech (high no_speech_prob, very low logprob, or looping output).
+ */
+function isChunkSilence(
+  segments:
+    | {
+        no_speech_prob?: number;
+        avg_logprob?: number;
+        compression_ratio?: number;
+      }[]
+    | undefined,
+): boolean {
+  if (!segments?.length) return false;
+  const n = segments.length;
+
+  const avgNoSpeech =
+    segments.reduce((s, seg) => s + (seg.no_speech_prob ?? 0), 0) / n;
+  if (avgNoSpeech > NO_SPEECH_THRESHOLD) {
+    console.log(
+      `[voice-ws] 🤫 silence (no_speech_prob=${avgNoSpeech.toFixed(2)})`,
+    );
+    return true;
+  }
+
+  const avgLogprob =
+    segments.reduce((s, seg) => s + (seg.avg_logprob ?? 0), 0) / n;
+  if (avgLogprob < LOW_CONFIDENCE_LOGPROB) {
+    console.log(
+      `[voice-ws] 🎲 low confidence (avg_logprob=${avgLogprob.toFixed(2)})`,
+    );
+    return true;
+  }
+
+  const avgCompression =
+    segments.reduce((s, seg) => s + (seg.compression_ratio ?? 0), 0) / n;
+  if (avgCompression > HIGH_COMPRESSION_RATIO) {
+    console.log(
+      `[voice-ws] 🔁 repetitive (compression_ratio=${avgCompression.toFixed(2)})`,
+    );
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Master transcript cleaner.
+ * 1. Reject pure punctuation/symbol outputs.
+ * 2. Strip known ghost phrases (preserves real speech in the same chunk).
+ * 3. Drop the chunk only if segment stats confirm total silence.
+ *
+ * Returns cleaned text, or "" if nothing real remains.
+ */
+function cleanTranscript(
+  rawText: string,
+  segments:
+    | {
+        no_speech_prob?: number;
+        avg_logprob?: number;
+        compression_ratio?: number;
+      }[]
+    | undefined,
+): string {
+  // 1. Pure punctuation / symbols
+  if (!rawText.trim() || HALLUCINATION_RE.test(rawText.trim())) return "";
+
+  // 2. Strip ghost phrases — may return "" if nothing real is left
+  const cleaned = stripGhostPhrases(rawText);
+  if (!cleaned) return "";
+
+  // 3. Segment-level silence check
+  if (isChunkSilence(segments)) return "";
+
+  return cleaned;
+}
+
+// ─── Whisper API ─────────────────────────────────────────────────────────────
+
+async function transcribeWithWhisper(
+  audioBase64: string,
+  ext: string,
+  mimeType: string,
+  prompt: string,
+): Promise<string> {
+  if (!ENV.forgeApiUrl || !ENV.forgeApiKey) {
+    throw new Error(
+      "STT API not configured. Set BUILT_IN_FORGE_API_URL and BUILT_IN_FORGE_API_KEY in .env " +
+        "(supports OpenAI, Groq, or any OpenAI-compatible Whisper API)",
+    );
+  }
+
+  const audioBuffer = Buffer.from(audioBase64, "base64");
+  if (audioBuffer.length < 500) {
+    console.log("[voice-ws] ⚠️ chunk too small (silence), skipping");
+    return "";
+  }
+
+  const mimeMap: Record<string, string> = {
+    m4a: "audio/m4a",
+    mp4: "audio/mp4",
+    webm: "audio/webm",
+    wav: "audio/wav",
+    mp3: "audio/mpeg",
+    ogg: "audio/ogg",
+  };
+  const resolvedMime = mimeMap[ext] ?? mimeType ?? "audio/m4a";
+  const blob = new Blob([audioBuffer], { type: resolvedMime });
+
+  const models = ["whisper-large-v3-turbo", "whisper-large-v3", "whisper-1"];
+  for (const model of models) {
+    try {
+      const fd = new FormData();
+      fd.append("file", blob, `audio.${ext}`);
+      fd.append("model", model);
+      fd.append("language", "ar");
+      // verbose_json gives us no_speech_prob per segment for silence detection
+      fd.append("response_format", "verbose_json");
+      fd.append("prompt", prompt);
+      fd.append("temperature", "0"); // 0 = deterministic, no guessing
+
+      const baseUrl = ENV.forgeApiUrl.endsWith("/")
+        ? ENV.forgeApiUrl
+        : `${ENV.forgeApiUrl}/`;
+      const endpoint = new URL("v1/audio/transcriptions", baseUrl).toString();
+
+      console.log(
+        `[voice-ws] 🔊 transcribing with ${model} (${Math.round(audioBuffer.length / 1024)}KB)`,
+      );
+
+      const res = await fetch(endpoint, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${ENV.forgeApiKey}`,
+          "Accept-Encoding": "identity",
+        },
+        body: fd,
+        signal: AbortSignal.timeout(10000),
+      });
+
+      if (!res.ok) {
+        const errText = await res.text();
+        if (
+          res.status === 404 ||
+          errText.includes("model") ||
+          errText.includes("not found")
+        ) {
+          console.warn(`[voice-ws] model ${model} not available, trying next`);
+          continue;
+        }
+        throw new Error(`Whisper ${res.status}: ${errText}`);
+      }
+
+      const data = (await res.json()) as {
+        text?: string;
+        segments?: {
+          no_speech_prob?: number;
+          avg_logprob?: number;
+          compression_ratio?: number;
+          text?: string;
+        }[];
+      };
+      const raw = data.text?.trim() ?? "";
+      console.log(`[voice-ws] ✅ ${model} → "${raw}"`);
+
+      const text = cleanTranscript(raw, data.segments);
+      if (text !== raw) {
+        console.log(`[voice-ws] 🧹 cleaned → "${text}"`);
+      }
+      return text;
+    } catch (err: any) {
+      const cause = err.cause?.message ?? err.cause?.code ?? "";
+      if (
+        err.name === "TimeoutError" ||
+        err.message?.includes("not available")
+      ) {
+        console.warn(`[voice-ws] ${model} timeout/unavailable, trying next`);
+        continue;
+      }
+      // "fetch failed" is a generic network error — log the root cause for debugging
+      if (err.message === "fetch failed") {
+        console.error(
+          `[voice-ws] ❌ fetch failed for ${model} — cause: ${cause || "unknown"}`,
+        );
+        throw new Error(`fetch failed (${cause || "network error"})`);
+      }
+      throw err;
+    }
+  }
+  throw new Error("All Whisper models unavailable");
+}
+
+// ─── WebSocket Server ────────────────────────────────────────────────────────
+
+function sendJson(ws: WebSocket, msg: Record<string, any>) {
+  if (ws.readyState === WebSocket.OPEN) {
+    ws.send(JSON.stringify(msg));
+  }
+}
+
+export function registerVoiceWebSocket(httpServer: Server) {
+  const wss = new WebSocketServer({
+    server: httpServer,
+    path: "/ws/voice",
+    perMessageDeflate: false,
+  });
+
+  // Log STT configuration on startup
+  if (ENV.forgeApiUrl && ENV.forgeApiKey) {
+    console.log(
+      `[voice-ws] ✅ STT API configured: ${ENV.forgeApiUrl} (server-side Whisper)`,
+    );
+  } else {
+    console.warn(
+      "[voice-ws] ⚠️ STT API NOT configured! Set BUILT_IN_FORGE_API_URL and BUILT_IN_FORGE_API_KEY in .env",
+    );
+    console.warn(
+      "[voice-ws]   Free option: Groq API → https://console.groq.com (whisper-large-v3-turbo)",
+    );
+    console.warn(
+      "[voice-ws]   Set BUILT_IN_FORGE_API_URL=https://api.groq.com/openai",
+    );
+    console.warn("[voice-ws]   Set BUILT_IN_FORGE_API_KEY=gsk_...");
+  }
+
+  wss.on("connection", (ws) => {
+    console.log("[voice-ws] 🔌 client connected");
+
+    const send = (msg: Record<string, any>) => sendJson(ws, msg);
+    const session = new VoiceSession(ws, send);
+
+    send({ type: "ready" });
+
+    ws.on("message", (raw) => {
+      let msg: ClientMessage;
+      try {
+        msg = JSON.parse(raw.toString());
+      } catch {
+        return;
+      }
+
+      console.log(
+        `[voice-ws] ← ${msg.type}${(msg as any).chunkId != null ? ` #${(msg as any).chunkId}` : ""}`,
+      );
+
+      if (msg.type === "stop") {
+        session.reset();
+        return;
+      }
+
+      // Pre-recognized text (from Web Speech API or legacy clients)
+      if (msg.type === "text" && msg.text) {
+        session.processText(msg.chunkId, msg.text);
+        return;
+      }
+
+      // Raw audio chunk — transcribe with Whisper
+      if (msg.type === "chunk" && msg.audio) {
+        // Check STT config before accepting chunks
+        if (!ENV.forgeApiUrl || !ENV.forgeApiKey) {
+          send({
+            type: "error",
+            message:
+              "Server STT not configured. Set BUILT_IN_FORGE_API_URL and BUILT_IN_FORGE_API_KEY.",
+            chunkId: msg.chunkId,
+          });
+          return;
+        }
+
+        const mimeType = msg.mimeType ?? "audio/m4a";
+        const ext = mimeType.split("/")[1]?.split(";")[0] ?? "m4a";
+        session.enqueue({
+          chunkId: msg.chunkId,
+          audioBase64: msg.audio,
+          mimeType,
+          ext,
+        });
+      }
+    });
+
+    ws.on("close", () => {
+      console.log("[voice-ws] 🔌 client disconnected");
+      session.reset();
+    });
+    ws.on("error", (err) => {
+      console.error("[voice-ws] ❌ socket error:", err);
+    });
+  });
+
+  console.log(
+    "[voice-ws] ✅ WebSocket registered at /ws/voice (server-side STT pipeline)",
+  );
+}

shared/_core/errors.ts

@@ -0,0 +1,19 @@
+/**
+ * Base HTTP error class with status code.
+ * Throw this from route handlers to send specific HTTP errors.
+ */
+export class HttpError extends Error {
+  constructor(
+    public statusCode: number,
+    message: string,
+  ) {
+    super(message);
+    this.name = "HttpError";
+  }
+}
+
+// Convenience constructors
+export const BadRequestError = (msg: string) => new HttpError(400, msg);
+export const UnauthorizedError = (msg: string) => new HttpError(401, msg);
+export const ForbiddenError = (msg: string) => new HttpError(403, msg);
+export const NotFoundError = (msg: string) => new HttpError(404, msg);

shared/const.ts

@@ -0,0 +1,5 @@
+export const COOKIE_NAME = "app_session_id";
+export const ONE_YEAR_MS = 1000 * 60 * 60 * 24 * 365;
+export const AXIOS_TIMEOUT_MS = 30_000;
+export const UNAUTHED_ERR_MSG = "Please login (10001)";
+export const NOT_ADMIN_ERR_MSG = "You do not have required permission (10002)";

shared/types.ts

@@ -0,0 +1,7 @@
+/**
+ * Unified type exports
+ * Import shared types from this single entry point.
+ */
+
+export type * from "../drizzle/schema";
+export * from "./_core/errors";

tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "extends": "expo/tsconfig.base",
+  "compilerOptions": {
+    "strict": true,
+    "types": [
+      "node",
+      "nativewind/types"
+    ],
+    "paths": {
+      "@/*": [
+        "./*"
+      ],
+      "@shared/*": [
+        "./shared/*"
+      ]
+    }
+  },
+  "include": [
+    "**/*.ts",
+    "**/*.tsx",
+    ".expo/types/**/*.ts",
+    "expo-env.d.ts",
+    "nativewind-env.d.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
+}