computersciencefreshmen · computersciencefreshmen · Jul 24, 2026 · Jul 24, 2026
diff --git a/README.en.md b/README.en.md
diff --git a/README.md b/README.md
diff --git a/SECURITY.md b/SECURITY.md
@@ -22,7 +22,7 @@ Please allow time for a fix and coordinated disclosure. After remediation, the p
 - Never enable demo seeding in production and never bake administrator credentials into an image or Compose file.
 - Store `VERIFICATION_CODE_SECRET`, SMTP, AI, and TURN credentials outside version control; grant access only to deployment operators and rotate them after suspected exposure.
 - Keep secure, HttpOnly session cookies enabled, disable bearer authentication unless an audited non-browser client requires it, and configure the trusted proxy boundary deliberately.
-- Back up both the SQLite database and uploaded files, encrypt backups, test restores, and restrict backup access.
+- Back up PostgreSQL data, encrypt backup dumps, test restores, and restrict access to both the private object bucket and the backup bucket.
 - Rebuild frequently from the lockfile and review dependency/security alerts before deploying.
 
 Deployment hardening, backup, restore, migration, and secret-handling procedures are documented in [docs/operations.md](docs/operations.md).

diff --git a/docs/adr/0001-self-contained-modular-monolith.md b/docs/adr/0001-self-contained-modular-monolith.md
@@ -1,7 +1,8 @@
 # ADR-0001：采用自包含模块化单体
 
-**状态：** Accepted  
-**日期：** 2026-07-19
+**状态：** Superseded by ADR-0003、ADR-0004 和 ADR-0005 · **日期：** 2026-07-19
+
+> **历史说明：** 这是最初的 SQLite、同进程部署决策。当前运行时使用 PostgreSQL、R2 兼容对象存储与 Vercel/Railway 分离部署；请以 ADR-0003 至 ADR-0006 为当前生产架构的事实来源。
 
 ## Context
 

diff --git a/docs/adr/0002-server-side-opaque-sessions.md b/docs/adr/0002-server-side-opaque-sessions.md
@@ -1,7 +1,8 @@
 # ADR-0002：使用服务端 opaque session
 
-**状态：** Accepted  
-**日期：** 2026-07-19
+**状态：** Partially superseded by ADR-0003 · **日期：** 2026-07-19
+
+> **历史说明：** 不透明服务端 Session 的安全模型仍然有效；当前实现把 Session 摘要保存在 PostgreSQL，而不是本文记录的 SQLite。数据存储事实以 ADR-0003 为准。
 
 ## Context
 

diff --git a/docs/adr/0005-vercel-railway-split-deployment.md b/docs/adr/0005-vercel-railway-split-deployment.md
@@ -5,7 +5,7 @@
 
 ## Decision
 
-Serve the Vue SPA from Vercel and the single-instance Fastify API from Railway. Vercel externally rewrites `/api/:path*` to Railway, while classroom WebSockets connect directly to the Railway WSS origin returned in the one-time ticket response.
+Serve the Vue SPA from Vercel and the single-instance Fastify API from Railway. Vercel externally rewrites `/api/v1/:path*` to Railway, while classroom WebSockets connect directly to the Railway WSS origin returned in the one-time ticket response.
 
 ## Consequences
 

diff --git a/docs/operations.md b/docs/operations.md
@@ -1,6 +1,6 @@
-# 公开 Beta 部署与运维手册
+# 公开 Beta 参考部署与运维手册
 
-本文档对应当前线上架构：Vercel 托管 Vue 前端和邮件中继函数，Railway 运行单实例 Fastify 与独立备份 Cron 服务，Railway PostgreSQL 保存业务数据，Cloudflare R2 私有 Bucket 保存文件与加密备份。
+本文档定义推荐的公开 Beta 部署拓扑：Vercel 托管 Vue 前端和邮件中继函数，Railway 运行单实例 Fastify 与独立备份 Cron 服务，Railway PostgreSQL 保存业务数据，Cloudflare R2 私有 Bucket 保存文件与加密备份。部署前应在自己的 Vercel/Railway/R2 账号中完成域名、Secret 与健康检查验收。
 
 ```text
 Browser ── HTTPS ──> Vercel ── /api/v1/* rewrite ──> Railway Fastify ──> PostgreSQL

diff --git a/docs/plans/2026-07-24-readme-information-architecture.md b/docs/plans/2026-07-24-readme-information-architecture.md
@@ -0,0 +1,38 @@
+# README information architecture overhaul
+
+- Date: 2026-07-24
+- Status: Implemented
+
+## Goal
+
+Rebuild the repository README as a first-class product and engineering entry point. A new reader should understand the platform in 30 seconds, run a verified local workflow in five minutes, and trace major architectural and security decisions within fifteen minutes.
+
+## Decision
+
+Use the visual hierarchy from the earlier portfolio-oriented README—brand hero, navigation, concise quality signals, workflow diagrams, and a completeness contract—while treating the current PostgreSQL, R2/MinIO, Vercel/Railway, and HMAC mail-relay implementation as the only runtime source of truth.
+
+The README remains an entry point rather than an operations manual. Detailed secrets, recovery, R2 CORS, and rollout steps stay in docs/operations.md. Historical SQLite-era plans and ADRs remain available as project history but are explicitly distinguished from current production decisions.
+
+## Reader flow
+
+1. Hero: project purpose, public-beta status, CI, and technology signals.
+2. Value: why persistent cross-role teaching workflows matter.
+3. Evidence: four server-enforced journeys and three role workspaces.
+4. Action: reproducible local quick start, readiness probe, and seeded demo accounts.
+5. Understanding: deployment topology, component responsibilities, and trust boundaries.
+6. Verification: Node tests, browser E2E, CI services, documentation, security, scope, and licensing.
+
+## Facts protected by the rewrite
+
+- Production API traffic uses only the /api/v1/* Vercel rewrite to Railway.
+- Railway sends a signed minimal payload to Vercel /api/mail-relay; Gmail credentials stay in Vercel.
+- PostgreSQL is the current database and R2/MinIO is the object-storage contract.
+- The public beta runs one API instance because classroom presence is currently process-local.
+- The test suite contains 71 Node tests and four cross-role browser workflows at the time of this rewrite.
+
+## Acceptance criteria
+
+- Chinese and English README files tell the same architecture story.
+- Every major claim links to code, a test, or a current operations/ADR document.
+- A reader can reach a ready API and seeded role account without hidden setup assumptions.
+- Limitations are explicit rather than disguised as production capability.