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 or newer
• npm

Install dependencies:

npm install

Generate assistant knowledge:

npm run assistant:index

Start the frontend:

npm run dev

Open:

http://localhost:5173

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

npm run prisma:generate
npm 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

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.