AGENTS.md

Guidance for coding agents working on AlexandrAI apps/web. The root repository guide covers the full workspace; this file focuses on the Hono server and Vite client package.

Project Overview

apps/web combines a Hono server with a Vite client. The server owns app creation, config loading, security middleware, CORS, rate limiting, auth routes, paper routes, public paper delivery, comments, markdown preview, Postgres stores, storage adapters, and static client serving. The client owns archive search, filters, rankings, reader behavior, comments display, install flow, navigation, labels, DOM helpers, and styles.

This app is public archive infrastructure. Changes must preserve upload validation boundaries, safe public previews, comment metadata separation, cache behavior, and storage abstraction.

Project Map

• src/server/app.ts creates the Hono app, wires stores, security middleware, body limits, static client serving, public routes, auth routes, paper routes, and comment routes.
• src/server/config.ts loads runtime configuration and limit settings.
• src/server/middleware contains auth and security middleware with focused tests.
• src/server/routes owns auth, paper, public paper, comment, and public comment routes.
• src/server/db contains store interfaces and Postgres implementations for accounts, papers, references, comments, pagination, and errors.
• src/server/storage contains filesystem and S3-compatible paper storage adapters.
• src/server/markdown-viewer.ts renders markdown-native archive items for public preview.
• src/client contains API helpers, filters, reader, labels, install, navigation, normalize, DOM utilities, types, and styles.

Setup Commands

~bash npm run dev -w @aipaper/web npm run build -w @aipaper/web npm run test -w @aipaper/web npm run test npm run typecheck npm run lint ~

Use local config files and environment variables for database and storage. Do not publish concrete private endpoints, local paths, or credentials.

Change Rules For Agents

• Keep public paper, public comment, auth, and upload behaviors behind server route boundaries.
• Preserve markdown-native preview safety: raw markdown, graph text, and rendered HTML are distinct surfaces.
• Do not bypass shared validation for report formats or research-paper payloads.
• Keep storage behavior behind the PaperStorage interface.
• Keep Postgres schema, store implementation, and route tests aligned when persistence changes.
• Do not add synchronous per-request filesystem reads for hot public routes when startup caching is available.
• Client API fallbacks should remain relative and same-origin; never hardcode deployment origins.

Verification

~bash npm run test -w @aipaper/web npm run build -w @aipaper/web npm run test ~

Run focused tests near route, store, markdown, security, config, or client helpers when touching those files.

Security Notes

Never publish API tokens, account tokens, password hashes, storage credentials, object keys, private database settings, or local filesystem paths. Keep body limits, rate limits, security headers, auth middleware, and relation-guarded comment attachment access intact.

PR Checklist

• Route and store changes have tests.
• Public preview surfaces remain escaped and metadata-only where required.
• Storage adapters remain interchangeable.
• Client calls remain same-origin and deployment-agnostic.
• Build and relevant tests pass.