BIAU Port / 泊岸

AI applications, project case studies, content studio, and a public research assistant for the BIAU Port ecosystem.

简体中文文档：README.zh-CN.md

BIAU Port / 泊岸 is a React + Vite + TypeScript product site that organizes AI products, business systems, mobile apps, interactive experiences, technical articles, a public research assistant, Studio drafts, and reliability status into one public-safe showcase.

Live site:

https://biau.playlab.eu.cc

Contents

• Preview
• What It Does
• Features
• Architecture
• Quick Start
• Configuration
• Development Scripts
• Deployment
• Project Structure
• Testing
• Security
• Roadmap
• License

Preview

These public-safe screenshots were refreshed from the local routes on 2026-07-10. The first-entry harbor intro was skipped during capture so the images show the stable visitor UI instead of the opening animation.

Projects	Blog

Use the live site or a local dev server for the current route state:

Surface	Route
Home	/
Projects	/projects
Blog	/blog
Status	/status
知航 BIAU Beacon public assistant	Public site routes
Content Studio	/studio
Pet app showcase	/pet-app-showcase/

Project screenshots and diagrams are tracked in docs/showcase-assets.md. Refresh the public-safe assets and run the relevant visual checks before replacing these README images.

What It Does

• Presents project case-study pages for 律航 LexBeacon, 商舱 OpsDeck, 帆灵 SailSprite, 寻球 BallTrail, 游湾 BIAU Playlab, and related apps.
• Publishes curated blog content, knowledge notes, project notes, resources, and 潮讯 TideBrief AI Daily drafts after review.
• Provides 知航 BIAU Beacon, a public LangGraph research assistant that adaptively combines BIAU knowledge and verified public-web evidence with claim-level citations.
• Previews 画帆 BIAU Canvas as a planned image-hosting tool without exposing a fabricated public URL or unverified availability claim.
• Provides a Content Studio for draft editing, AI Daily issue management, source items, reviews, and publish export records.
• Tracks public link health, synthetic checks, project reliability status, manual gates, and low-sensitive observability boundaries.

Features

• React 19, Vite, TypeScript, React Router, custom token-based CSS, and Lucide icons.
• Public project catalog with filters, detail pages, screenshots, workflow visuals, architecture notes, quality evidence, limitations, and roadmap sections.
• Public assistant knowledge generation with docs, chunks, entities, relations, deterministic local eval, and public-only citation boundaries.
• Cloudflare Pages Functions for same-domain public assistant endpoints.
• Express backend with public, studio, rag, and local all service modes.
• One server-only Responses generation model with bounded planning, research, evidence grading, recovery, generation, and verification.
• Public-only RAG Orchestrator with server-only Supabase pgvector, exact 4096-dimensional cosine search, keyword/entity expansion, a sync token, and optional embedding/reranker adapters. A Qdrant adapter remains available only for compatibility and rollback tests.
• Prisma/PostgreSQL persistence for bounded anonymous assistant sessions/turns/feedback plus Studio drafts, AI Daily issues, source items, reviews, and publish exports.
• Studio-first AI Daily flow: source pool -> issue -> hidden/review-needed draft -> review -> publish export -> static content diff.
• Default-off analytics adapter for Plausible, Umami, or local debug events.
• Default-off Prometheus /metrics endpoint for assistant services.
• Local verification suite covering assistant knowledge, RAG smoke, service-mode isolation, Studio smoke, blog checks, project detail evidence, status contracts, UI checks, lint, and build.

Architecture

flowchart TB
  Browser["Browser\nReact + custom CSS"] --> Pages["Cloudflare Pages\nstatic site + Functions"]
  Pages --> PublicAPI["Public assistant API\nASSISTANT_SERVICE_MODE=public"]
  Browser --> StudioAPI["Content Studio API\nASSISTANT_SERVICE_MODE=studio"]
  PublicAPI --> RAG["RAG Orchestrator\nASSISTANT_SERVICE_MODE=rag"]
  PublicAPI --> LangGraph["Public-only LangGraph\nplan / research / grade / verify"]
  PublicAPI --> AppDB["Public assistant PostgreSQL\nanonymous turns / feedback / aggregates"]
  StudioAPI --> StudioDB["Studio PostgreSQL\ndrafts / sources / AI Daily / exports"]
  RAG --> Pgvector["Supabase pgvector\npublic 4096-dimension chunks"]
  RAG --> Embedding["Embedding provider\nserver-only"]
  PublicAPI --> Model["OpenAI-compatible model\nserver-only"]

Loading

Recommended production shape uses three independent Render Web Services from the same repository:

Service	Mode	Owns
biau-public-assistant-api	public	Public chat API and public-only retrieval.
biau-content-studio-api	studio	Drafts, reviews, source items, AI Daily issues, publish exports.
biau-rag-orchestrator	rag	Public-only retrieval, transactional sync, Supabase pgvector, embedding, optional rerank.

Detailed docs:

• Deployment
• Content Studio
• AI Daily Pipeline
• Site Monitoring
• Observability Strategy
• Manual Gates Ledger

Quick Start

Requirements:

• Node.js 22.x, at least 22.13.0 (recommended to match CI), or Node.js 24.x
• npm, included with Node.js

Use the latest patch of your chosen Node branch. The minimum version follows the committed dependency requirements, including ESLint 10.

The examples below use PowerShell 7 on Windows. On macOS or Linux, use npm with the same arguments in place of npm.cmd.

Check the active versions:

node --version
npm.cmd --version

For a fresh checkout, install the versions recorded in package-lock.json, matching CI:

npm.cmd ci

Generate assistant knowledge:

npm.cmd run assistant:index

Start the frontend:

npm.cmd run dev

Open:

http://localhost:5173

Start the local Express backend when working on assistant, Studio, or RAG APIs:

npm.cmd run prisma:generate
npm.cmd run server:dev

Local server default:

http://localhost:8787

Configuration

Frontend variables are public and must use VITE_*. Server credentials must never be placed in VITE_*.

Common frontend variables:

Variable	Purpose
VITE_CHAT_API_BASE_URL	Public assistant API base, often /api for Cloudflare Pages Functions.
VITE_STUDIO_API_BASE_URL	Content Studio API origin.
VITE_AI_DAILY_API_BASE_URL	Public AI Daily feed origin; no browser token is sent.
VITE_ANALYTICS_PROVIDER	Optional umami, plausible, or debug. Default is off.

Common server variables:

Variable	Purpose
ASSISTANT_SERVICE_MODE	public, studio, rag, or local all.
CORS_ORIGIN	Browser origin allowed by Express services.
AI_DAILY_PUBLIC_*	Public AI Daily CORS allowlist, time window, stale threshold, and process-local rate limit.
DATABASE_URL	Anonymous public assistant session/turn/feedback database.
STUDIO_DATABASE_URL	Content Studio database.
ADMIN_TOKEN / STUDIO_ADMIN_TOKEN	Server-side admin tokens.
ASSISTANT_MODEL_*	Server-side OpenAI-compatible model channel.
ASSISTANT_RAG_API_BASE_URL / ASSISTANT_RAG_API_KEY	Server-side RAG Orchestrator access from assistant APIs.
RAG_STORE_PROVIDER / RAG_DATABASE_URL	Production Supabase pgvector store or local fallback behavior.
RAG_PUBLIC_API_KEY / RAG_SYNC_TOKEN	Public retrieval and publication-sync credentials.
EMBEDDING_* / RERANKER_*	Server-side embedding and optional rerank providers.
METRICS_ENABLED	Enables low-sensitive Prometheus metrics when set to true.

Use placeholders in docs and examples. Put real keys, database URLs, model base URLs, tokens, vector-store keys, and provider endpoints only in your local environment or deployment platform.

Development Scripts

Development uses Codex with AGENTS.md as the project instruction entry and the Codex workflow as the operating guide. Trellis runs in inline mode: the main Codex session implements and verifies changes using the existing project specs and skills.

npm run dev
npm run build
npm run lint
npm run preview

Assistant and RAG:

npm run assistant:index
npm run assistant:kg-check
npm run assistant:eval
npm run assistant:rag-sync-local
npm run assistant:rag-smoke
npm run assistant:service-modes-smoke
npm run server:build
npm run server:smoke

Studio, blog, and AI Daily:

npm run studio:smoke
npm run studio:export -- --sample --dry-run
npm run blog:audit
npm run blog:check
npm run blog:knowledge-check
npm run ai-daily:draft

Reliability and public site checks:

npm run site:monitor
npm run public-links:check
npm run reliability:check
npm run project-details:check
npm run status:contract
npm run check:ui

These commands inspect current behavior without changing committed status snapshots. Use npm run reliability:publish or the matching *:publish command only when the checked evidence is intentionally ready for publication.

Broad local gate:

npm run verify

The default verification suite is designed to avoid live model-provider calls. Real model calls should be tied to an approved content or assistant task, not a generic liveness probe.

Deployment

Static Site

Recommended host: Cloudflare Pages.

Build command: npm run build
Build output directory: dist
Production branch: main
NODE_VERSION=22

Cloudflare Pages Functions can serve same-domain public assistant endpoints under /api.

Render Services

The repository includes render.yaml as a Blueprint reference for the three services. All secret-bearing variables use sync: false and must be filled in the Render dashboard.

Typical commands:

# public
npm ci && npm run assistant:index && npm run prisma:generate && npm run server:build
npm run prisma:migrate && npm run server:start

# rag
npm ci && npm run assistant:index && npm run prisma:generate && npm run server:build
npm run server:start

# studio
npm ci && npm run prisma:generate && npm run server:build
npm run prisma:migrate:studio && npm run server:start

See docs/deployment.md for service-specific environment variables, migration order, CORS rules, Supabase pgvector setup, the optional Qdrant adapter boundary, and Cloudflare Function checks.

Project Structure

src/
  pages/          Public routes, project details, and Studio UI
  components/     Shared React UI components
  data/           Public project/blog/assistant/status data contracts
  utils/          SEO, analytics, visual and browser helpers
server/
  src/            Express app, service modes, LangGraph runtime, RAG routes, Studio routes
  scripts/        Smoke tests and local RAG/service checks
  data/           Generated public assistant knowledge
functions/
  api/            Cloudflare Pages public assistant functions
prisma/
  schema.prisma   Assistant and Studio persistence schema
scripts/
  *.ts/*.mjs      Content, status, sitemap, monitoring, and verification scripts
docs/
  *.md            Deployment, Studio, AI Daily, monitoring, observability, manual gates
public/
  images/         Public-safe project screenshots and diagrams
  status/         Generated low-sensitive status snapshots

Testing

Minimum check for README/docs-only edits:

npm run docs:manual-gates-check

Recommended check for frontend or public data changes:

npm run lint
npm run build

Recommended check for assistant/backend/RAG changes:

npm run assistant:index
npm run assistant:eval
npm run prisma:validate
npm run server:build
npm run server:smoke
npm run assistant:service-modes-smoke
npm run assistant:rag-smoke

Full release confidence:

npm run verify

Security

• Treat everything committed to this repository as public.
• Do not commit .env, .env.local, keys, database URLs, model base URLs, API keys, bearer tokens, service/admin tokens, signing paths, or private dashboards.
• Do not put model, RAG, database/vector-store, Studio, or admin credentials in VITE_*.
• Public assistant answers must be grounded in public citations and must refuse or fall back when context is insufficient.
• Public assistant tools are anonymous, read-only, public-evidence-only, and cannot publish content or mutate project/cloud state.
• Studio drafts stay hidden + review-needed until a human reviews and exports them.
• Debug APKs or unapproved release artifacts must not be linked as official public downloads.

Roadmap

• Finish open-source packaging for all related repositories with consistent README, setup, deployment, testing, and security sections.
• Improve project detail pages with richer screenshots, architecture diagrams, workflow visuals, and public-safe evidence.
• Continue polishing public assistant retrieval, verified web evidence, citations, self-check, and production RAG sync.
• Add first-class scheduled reliability checks and artifact-based status publishing.
• Decide and document a production analytics/observability stack: Cloudflare + Search Console + Plausible/Umami first, Prometheus/Grafana/OpenTelemetry/LLM observability later when justified.

License

This repository is licensed under the Apache License 2.0.