probably-rendering-one-more-pixel-tonight/docs/monorepo.md

PROMPT monorepo

• apps/waterfall-wiki: existing Pages Router application, media library, PostgreSQL, object storage and video processing worker. /wiki/Namespace:slug has matching /api/wiki/Namespace:slug Markdown; /api/wiki-index discovers pages. Existing /p/slug has /api/wiki-post/slug and alternate metadata. Main/File/Category/Template/Draft/Help are public content types, not permission boundaries. Categories cross namespaces; template pages currently describe reusable structures rather than a transclusion engine.
• apps/studio: independent Next.js + TypeScript + Tailwind Pages Router. Add ideas in src/content/ideas.ts, open /ideas/slug, export Markdown or versioned JSON, or print to PDF. Add custom React pages under src/pages when a composition needs bespoke rendering.
• apps/python: install with pip install -e apps/python. Run prompt-export idea.json --output ./output --font /path/to/cjk.ttf [--video]. Generates 1080×1440 PNGs and an optional silent MP4 (4 seconds per slide), requiring FFmpeg. JSON describes standard slides; arbitrary React animations need a separate browser recording pipeline. Python Docker image includes CJK fonts and FFmpeg.

Development

Node 24, pnpm 11.25.0, Python 3.12+. pnpm install; pnpm dev:waterfall-wiki; pnpm dev:studio. Do not use local preview for acceptance; see root AGENTS.md. Each JS application owns its frozen pnpm lockfile. Production Docker builds install each project independently.

Releases

Three path-filtered Gitea workflows run on ces-control. Changes to one app trigger that app only. Workspace configuration changes intentionally verify both JS applications. Documentation changes do not deploy. Each workflow can be manually dispatched for recovery after a failed release. All app content, including Markdown, triggers its workflow.

Wiki keeps /opt/prompt, port 18131 and existing persistent volumes. Studio uses its own Compose project, /opt/prompt-studio, port 18134, and verifies its AI index before recording the release; port 18134 is bound to loopback so access goes through Wiki authentication. Python publishes prompt-python:<sha> and the local latest alias, used on demand rather than running an empty daemon. No Python network port is exposed. Root Dockerfile is Wiki's build entry; apps/waterfall-wiki/Dockerfile mirrors it for discovery.

CI uses root build context and application-scoped COPY instructions. Wiki runs its existing Docker integration suite before deploying. The former Web-only release path is retired because its source-copy and image assumptions predated the monorepo. No down -v is used in production.

Explore 页面与轻量图片

首页 / 与分类 /categories 统一浏览；内容固定地址 /explore/<id>。文档 ID 持久保存在 apps/waterfall-wiki/src/content/page-ids.json，改标题或位置时保留 ID；数据库素材使用原有 UUID。旧 /skills/...、/p/... 和 /wiki/... 网页跳转到内容地址，媒体与纯文本 API 保持兼容；Wiki 不再提供截图画布与截图任务。?agent_mode=True（大小写不敏感）在相同地址返回 text/plain，保留全部正文与媒体链接。

/api/preview 只接受本站静态栅格图或媒体 ID，限制四档尺寸，输出 WebP：列表目标最多 100 KB、详情目标最多 220 KB。原图按需下载。服务端预览使用并发限制、请求合并、磁盘缓存和 ETag；缓存数量有限并定期清理。SVG 图标不经过栅格化。

Studio 部署到同一 Docker 网络，通过 http://8.211.154.134:18131/studio 访问，不依赖额外公网端口。直连端口 127.0.0.1:18134/studio 仅服务器本机可用；公网访问统一经过 Wiki 登录保护。

Docker 在单独的依赖下载层执行 pnpm fetch，再离线安装。源码变化复用依赖层，包脚本变化复用已下载的包。CI 不清理 Docker 缓存，不使用 --no-cache。

扁平标签与资源引用

posts 保留稳定 UUID、兼容 slug、标题、description、类型、封面资源 ID 与时间；移除代码页绑定 page_key。tags 为全局唯一名称，不含 parent_id，输入 #标签 并回车可创建或复用；post_tags 和 asset_tags 仍是多对多关联。静态 Wiki 页面目前仍使用代码内容，发布步骤将其可见标签同步到标签表。

所有文件统一进入 assets。视频加工结果通过 source_asset_id 和 derivation 记录来源，并以 post_assets 的 silent_video、audio_track、poster 角色供笔记引用；它们可以像其他资源一样复用。旧 ?variant= 媒体地址继续读取相应普通资源。保留 media_jobs 用于异步处理和失败重试，保留 contribution_events，不再使用 asset_variants、page_snapshots、render_jobs。已有截图转换成普通图片引用后保留。创作站与 Python 导出功能独立运行。

部署在停止 Wiki 写入后备份数据库，再运行迁移和启动新版；失败时使用同一备份恢复旧版所需的数据库结构。对象文件和持久卷保留。

内部应用名统一为 waterfall-wiki，网站品牌为 PROMPT。Compose 业务服务为 waterfall-wiki / waterfall-wiki-worker，镜像参数为 WATERFALL_WIKI_IMAGE / WATERFALL_WIKI_TEST_IMAGE；历史 prompt 项目与持久卷保留。系统标签为固定文档入口/参考图，普通标签可通过 # 新建，详见根 README。