SForum: Instructions file for Codex

Agent Guide

This file is the shared working agreement for SForum. Read it before starting any new session. It is intentionally self-contained: do not assume contributors have the same personal or global Codex instructions. Personal defaults may supplement this file, while more specific repository instructions take precedence within their directory scope.

Project Intent

SForum is a maintainable, plugin-first, open-source forum framework. Core is the host framework; product verticals and provider/vendor behavior live in extensions. The repository is past scaffolding and actively implementing core forum, identity, admin, and extension systems.

Working Principles

• Prefer mature third-party libraries before building custom infrastructure. Before starting a module or feature, briefly check whether established libraries already solve the core problem well.
• Avoid messy, tightly coupled code. Keep responsibilities clear, name things plainly, and make the easy path maintainable.
• Split long implementations across multiple focused files. Avoid placing more than 1000 lines in one file unless there is a strong, documented reason.
• Keep changes scoped to the current task. Do not refactor unrelated areas just because they are nearby.
• Record decisions in the knowledge base when they will matter to future sessions.

Stack And Directory Map

Monorepo with a Go API plus a Nuxt web app, plus shared contracts, extensions, knowledge base, and tests.

• apps/api — Go 1.26.10 API + background worker (toolchain anchored in apps/api/go.mod; do not let docs lag behind it). Module path github.com/zhuchunshu/sforum/apps/api. Laravel-style Go layout:
  • cmd/ — api (HTTP server), worker (River queue worker), migrate (embedded Goose migrator), sforum (developer CLI; scaffolds plugins/themes, runs seed:forum).
  • bootstrap/ — runtime assembly; NewWorker for the worker process.
  • app/Http/ — HTTP kernel, controllers, and route registration (app/Http/Controllers/*).
  • app/Models/ — domain logic and services.
  • app/Providers/ — provider wiring (mail provider slot, attachment storage adapters, search, cache, etc.).
  • app/Support/ — cross-cutting infra: Jobs (River durable queue), Search (host framework + site PG FTS; optional Meili plugin), Cache (Redis CachedStore decorator).
  • database/ — migrations/ (Goose SQL), migrator/ (shared embedded migrator), queries/ + sqlc/ (sqlc-generated code; config in sqlc.yaml).
  • config/ — runtime config loaders. config.Load does NOT read .env; the dev scripts source .env and export vars explicitly.
• apps/web — Nuxt 4 / Vue 3 / Nuxt UI 4 frontend (package name @sforum/web). SSR-first (no ssr: false remains anywhere). Key deps: Bun, Tailwind, @nuxtjs/i18n, Tiptap, DOMPurify, altcha, @iconify-json/tabler + @iconify-json/lucide. App code lives under apps/web/app/{components,composables,pages,layouts,middleware,plugins,config} with the uppercase SF prefix component library, and admin pages under apps/web/app/pages/admin. i18n default locale zh-CN, secondary en-US.
• contracts/ — modular OpenAPI contract. openapi.yaml is the entrypoint index only; paths in openapi/paths/<module>.yaml, schemas in openapi/schemas/<module>.yaml, shared components in openapi/components/.
• extensions/ — package trees; only builtin/ is boot-scanned into the admin list (SyncBuiltins). Also dev/ (gitignored scaffolds), optional/ (ship-with-repo, operator install), fixtures/ (CI). Layout map: extensions/README.md. Container images copy built-ins to /app/extensions/builtin.
• knowledge/ — project memory: index.md, modules/, decisions/, sessions/, glossary.md, research.md. Read before sensitive work.
• tests/ — repo-level validation scripts (Playwright/Node) that hit the running dev servers.
• scripts/ — dev/test orchestration shell scripts (see Commands below).
• docs/ — bilingual handbooks (zh-CN/, en-US/) plus path-stable extension reference under docs/extensions/; historical material in docs/archive/.
• deploy/, compose*.yaml, deploy.sh — deployment and ops.
• Runtime deps via Compose: PostgreSQL, Redis, Mailpit (Meilisearch optional via --profile search).