01 — Overview#
1.1 What KodePress is#
KodePress is a self-hosted website CMS. The owner of a small business, school, clinic or news site logs into one admin panel and builds the entire public website there: pages, blog, navigation, header, footer, colours and fonts. Nothing requires a developer after installation.
It is deliberately not a framework for developers to build apps on. It is a website builder with a CMS behind it, shaped around one person doing everything themselves.
1.2 The one goal#
A person who has never seen the product publishes their first page in under 10 minutes, with no training and no documentation.
Everything else is subordinate. When a feature makes the product more capable but the first ten
minutes slower, the feature is wrong or it belongs behind an Advanced disclosure.
Three design consequences follow directly:
- One editor, learned once. Pages, blog posts, headers, footers, mega-menu panels and reusable sections all use the same section/column/block editor. There is no second mental model.
- Never start from blank. New sites pick a template. New pages pick a template. New sections come from a gallery of finished designs. A blank canvas is an expert feature.
- The design cannot be broken. Colours, fonts and spacing come from theme tokens. Free-form CSS
exists, but only under
Advanced, and only for roles that can be trusted with it.
1.3 Who uses it#
| Persona | Technical level | What they do | What must never happen |
|---|---|---|---|
| Owner / Admin | None | Installs, picks a theme, edits pages, adds staff, reads form submissions | Faced with YAML, JSON, FTP or "ask your developer" |
| Editor | Low | Writes and publishes pages and posts, edits menu items | Able to break the header or theme for the whole site |
| Writer | Low | Writes drafts, submits for approval | Able to publish without review (when approval is on) |
| Designer | Medium | Builds header, footer, mega menu, theme | Able to read form submissions or manage users |
| Developer (occasional) | High | Adds a custom block or plugin, deploys | Having to modify admin code to add a block |
1.4 Scope#
In scope#
- Page builder with a block library, section gallery, drag and drop, undo/redo, autosave, versions
- Blog: posts, categories (nestable), tags, authors, excerpts, featured images, scheduled publishing
- Public blog surfaces: post, category, tag, author, search, RSS
- Menu manager: multiple menus, locations, three levels, item types, visibility rules
- Mega menus built with the page editor, degrading to an accordion/drawer on mobile
- Header and footer manager with presets, multiple named parts, conditional assignment, versions
- Theme tokens with four presets and generated CSS
- Media library with automatic compression, WebP, size variants and alt-text prompting
- Form builder with email notification, submissions list, CSV export, honeypot and rate limiting
- SEO per page,
sitemap.xml,robots.txt, automatic 301 on slug change, redirect manager - Roles and permissions, optional publish approval, audit log
- Bengali + English UI and bilingual public pages
- Backup/restore of database and media, chunked for shared hosting
- Inline editing from the public site when logged in
- Multi-site and a plugin system (Phase 5)
Explicitly out of scope#
| Not building | Why |
|---|---|
| E-commerce, cart, checkout, payments | A separate product; a plugin may add it later |
| Membership / paid subscriptions | Same |
| Headless/decoupled front end, public content API | Contradicts "no Node at runtime" and the HTML cache model |
| Visual drag-anywhere canvas (absolute positioning) | Breaks responsive output and breaks the design-token promise |
| Real-time multi-user co-editing | Needs websockets; shared hosting cannot run them |
| Theme marketplace with PHP themes | Theme = tokens + templates; arbitrary PHP themes reintroduce "ask your developer" |
| Automatic Laravel major-version upgrades | A deliberate, tested migration each time |
1.5 Non-functional requirements#
| Requirement | Target | How it is met |
|---|---|---|
| Public page load | < 1 s to first byte on shared hosting, cached | Published HTML served from the file cache (13) |
| Admin responsiveness | Editor interaction < 200 ms perceived | Livewire for state, Alpine for local interaction, no full reloads |
| Hosting floor | Shared cPanel, PHP 8.3, MySQL 8, SSH, one cron entry | No Redis/queue/Node/root anywhere (02) |
| Install time | Under 5 minutes from git clone to a working site |
php artisan kodepress:install does everything (14) |
| Accessibility | Keyboard-operable admin; public output has landmarks, alt text, visible focus | Alt-text prompt is part of the image field; presets ship accessible markup |
| Localisation | 100 % of UI strings in bn and en |
No literal UI text in code; a test asserts key parity |
| Data safety | No destructive action without undo or a named confirmation | Trash + restore, version history, in-app confirm modals |
1.6 Success criteria (how we know it works)#
These are the acceptance gates, restated as checks in 15-testing-and-qa.md:
- A new user publishes a page in 10 clicks or fewer, starting from a template.
- A new block type is added by creating one folder — admin code is untouched.
- A three-level menu with a mega menu renders as a panel on desktop and an accordion on mobile.
- Header and footer support preset switching, conditional assignment, drafts and version restore.
- A cached public page responds in under one second on the target shared host.
- Deployment to shared cPanel needs only SSH:
git pull,composer install,migrate, install. - A Writer cannot publish; a Designer cannot touch content or users.
php artisan testis green.
1.7 Naming#
- Product name: KodePress (one word, capital K and P).
- Composer package:
kodepress/kodepress. Application namespace staysApp\(Laravel convention). - Install command:
php artisan kodepress:install. The aliascms:installis kept so older notes and scripts keep working. - Config file:
config/kodepress.php. Cache directory:storage/app/kodepress-cache/. - Database table prefix: none. Table names are plain (
pages,menus, …) per 03-database-schema.md.
KodePress documentation · generated from the Markdown sources by
tools/build-docs-site.py · internal preview, not indexed.