GoPress Docs
Docs / Project Structure

Project Structure

go-press/
  cmd/
    server/        server entrypoint
    gendoc/        Swagger generation command
  core/            engine, domains, protocol-neutral Agent runtime, admin, extensions, cache
  themes/          built-in and custom themes
  plugins/         built-in and custom plugins
  internal/autoload/ generated extension imports
  sites/           per-host runtime configuration
  pkg/             shared infrastructure packages
  config/          default configuration and config discovery
  docs/            Swagger output and guide documentation
  uploads/         runtime media files and generated variants
  version/         GoPress version constants

Core

core/ contains the framework runtime:

  • engine.go, bootstrap.go, migrate.go, and seeder.go manage startup, migrations, and demo import.
  • content/ owns content, metadata, content types, repositories, queries, and request scopes.
  • agent/ owns protocol-neutral tools, principals, credentials, scope/RBAC authorization, execution policy, idempotency, and Agent audit.
  • audit/ contains the cross-transport audit model shared outside the admin package.
  • theme/ provides the theme interface, BaseTheme runtime, page-bundle loading, template helpers, SEO helpers, and fallback templates.
  • plugin/ defines the plugin interface.
  • admin/ implements the CMS admin UI.
  • taxonomy/, comment/, and user/ own classifications, comment threads, public/admin authentication, sessions, roles, and capabilities.
  • rewrite/ owns public URL resolution, canonical metadata, redirects, and sitemap generation.
  • cache/, worker/, media/, menu/, option/, i18n/, hook/, mail/, api/, and installer/ provide the remaining shared engine services.

Themes

Themes live under themes/{slug} and usually contain:

theme.go
theme.toml
locales/
demo/data/seed.toml
static/
templates/
  layouts/
  partials/
  pages/

They register with core from init() and are activated by slug.

Themes commonly split custom handlers and typed view assembly into handlers.go and services.go, and may register translatable settings from translatable.go. Core contract tests live under internal/contracts, keeping the themes/ root reserved for theme packages.

Plugins

Plugins live under plugins/{slug} and contain plugin.toml plus at least one root Go source file. A plugin can register hooks, settings pages, protected routes, database tables, admin templates, middleware, identity providers, and frontend output through core extension points.

Bundled examples cover multilingual content and Category/Tag identities, per-content SEO, code injection, self-hosted analytics, the disabled-by-default MCP adapter, and external identity. Plugin-owned tables use dbprefix.PluginTable; runtime implementations do not import themes.

plugins/gopress-mcp owns only MCP transport, protocol compatibility, Bearer authentication mapping, and its admin controls. It invokes the generic Core Agent Executor rather than importing content repositories or themes.

Runtime Sites

sites/{host}/config.toml is generated by the installer or maintained by operators. Generated site configuration should normally be ignored by Git.

Each site can also contain sites/{host}/public/ for generated public artifacts owned by that site. The admin sitemap generator writes sites/{host}/public/sitemap.xml; future generated files such as robots.txt or llms.txt should use the same site-scoped directory.

uploads/YYYY/MM/ stores original media and generated responsive variants. Site configuration, credentials, uploads, and generated artifacts are runtime data and are normally excluded from public source control.