# Cicadel

Cicadel brings Django’s structure and development speed to Go, with an AI-first philosophy, modern design and Go’s fast runtime.

## Philosophy

Building a complete web application should feel coherent and move quickly. Cicadel combines Django-familiar projects, apps, settings and routes with Go’s type safety, compiled performance and straightforward deployment.

AI-first means designing for developers and their AI tools: predictable conventions, explicit contracts, typed components and clear documentation make applications easier to understand, generate and maintain. Modern design starts with composable `.templ` components, typed props and slots, and a first-party Tailwind CSS workflow.

GORM and PostgreSQL provide the data foundation, while core batteries are composed through installable Go modules. The goal is Django-like productivity with the performance and simplicity of Go.

[Documentation](https://cicadel.fauzaanu.com/en/0.2.0/) · [Get started](https://cicadel.fauzaanu.com/en/0.2.0/intro/tutorial/index.md) · [API reference](https://cicadel.fauzaanu.com/en/0.2.0/ref/api/index.md) · [Architecture](https://cicadel.fauzaanu.com/en/0.2.0/internals/architecture/index.md) · [MIT license](https://github.com/fauzaanu/cicadel/blob/95c6008bf0ac6f1e5b611172fb1771f51395b36a/LICENSE)

> [!IMPORTANT]
> **Status: v0.2.0 — ready for building applications.** The core framework is released, documented and tested against real PostgreSQL, and released APIs follow the [stability guarantee](https://cicadel.fauzaanu.com/en/0.2.0/releases/releases/index.md#stability-guarantee). The next release adds security-header defaults; see the [readiness checklist](#readiness-checklist). Administration and other Django contrib extras are not required to build an application and come later as packages.

## Progress overview

**Implemented** = the linked scope has recorded implementation evidence. **Partial** = working foundations with broader contracts still open. Neither means stable or production-ready.

| Workstream | Status | Delivered scope | Evidence / remaining work |
| :--- | :---: | :--- | :--- |
| Application foundation | 🟢 Implemented | Registration, settings, routing, lifecycle, scaffolding, command help, deployment checks and development reload | [Foundation contracts and evidence](https://cicadel.fauzaanu.com/en/0.2.0/internals/foundation/index.md) |
| Component UI | 🟢 Implemented | Typed props, children, named slots, escaping, library exports and overrides | [Verification](https://cicadel.fauzaanu.com/en/0.2.0/sources/docs/component-verification.md) · [Authoring](https://cicadel.fauzaanu.com/en/0.2.0/howto/component-authoring/index.md) |
| Tailwind workflow | 🟢 Implemented | Pinned standalone tool, CSS generation and offline UI checks | [Build workflow](https://cicadel.fauzaanu.com/en/0.2.0/howto/tailwind/index.md) |
| Typed forms and model forms | 🟢 Implemented | Binding, validation, widgets, authorized saves, stale-edit checks and bounded uploads | [Forms contract](https://cicadel.fauzaanu.com/en/0.2.0/topics/forms-completion/index.md) · [Model forms](https://cicadel.fauzaanu.com/en/0.2.0/topics/model-forms/index.md) |
| Formsets | 🟢 Implemented | Atomic add/edit/delete collections and authorized inline editing | [Core installable module](https://cicadel.fauzaanu.com/en/0.2.0/ref/formsets/index.md) |
| Browser accounts | 🟡 Partial | Sign-in, recovery, password changes, logout and session revocation | [Starter and boundaries](https://cicadel.fauzaanu.com/en/0.2.0/topics/authentication/index.md); broader identity/admin work remains |
| Model-driven migrations | 🟡 Partial | Recorded model history, reviewable SQL, dependency graphs and supported recovery | [Acceptance evidence](https://cicadel.fauzaanu.com/en/0.2.0/sources/contrib/migrations/ACCEPTANCE.md); documented PostgreSQL subset |
| Installable apps | 🟡 Partial | Manifests, dependency checks, commands, resources, migrations and lifecycle | [Package checklist](https://cicadel.fauzaanu.com/en/0.2.0/sources/batteries.md#package-system-acceptance-checklist); contracts and extraction remain |
| Email | 🟢 Implemented | Verified-TLS SMTP, MIME, attachments, reusable batches and development backends | [Supported contract](https://cicadel.fauzaanu.com/en/0.2.0/topics/email/index.md) |
| Logging | 🟢 Implemented | Named routing, levels, handlers, rotation, redaction and correlated errors | [Supported contract](https://cicadel.fauzaanu.com/en/0.2.0/topics/logging/index.md) |
| Administration | ⚪ Extra | Model CRUD, forms and inline integration | Not required for readiness; full ADMIN-01–04 scope comes after the core ([inventory](https://cicadel.fauzaanu.com/en/0.2.0/sources/batteries.md)) |
| Cache, storage and jobs | 🟡 Partial | Storage interfaces, process-local caching and River integration | [Integrations](https://cicadel.fauzaanu.com/en/0.2.0/topics/extensions/index.md); complete backend and lifecycle contracts remain |
| Application testing | 🟡 Partial | Lifecycle fixtures, cookie-aware clients, disposable PostgreSQL databases and query budgets | [Testing guide](https://cicadel.fauzaanu.com/en/0.2.0/topics/testing/index.md); broader test-backend contracts remain |
| Operations and performance | 🟡 Partial | Operational guidance, benchmark evidence and CI checks | [Operations](https://cicadel.fauzaanu.com/en/0.2.0/howto/operations/index.md) · [Measurements](https://cicadel.fauzaanu.com/en/0.2.0/howto/performance/index.md); external validation remains |

## Completed implementation milestones

Checked items describe bounded work recorded in [PLAN.md](https://cicadel.fauzaanu.com/en/0.2.0/sources/PLAN.md), not completion of every related battery.

- [x] Establish architecture decisions and PostgreSQL-backed ORM/migration prototypes.
- [x] Deliver the request → route → database → rendered-page workflow.
- [x] Scaffold projects and apps with management commands and a complete tutorial.
- [x] Add sessions, CSRF protection and authorized editing to the example application.
- [x] Replace the prototype UI authoring model with compiled components.
- [x] Verify component composition in a generated host using an external library.
- [x] Deliver typed forms, model forms, formsets and admin inline integration.
- [x] Generate reviewable migrations from explicitly registered model declarations.
- [x] Verify the documented PostgreSQL migration subset and upgrade/recovery paths.
- [x] Deliver the browser accounts starter, email and configurable logging.
- [x] Build a second example application with different relationships and permissions.
- [x] Record operational guidance, performance methodology and release policy.

## Readiness checklist

This is the priority list: future work starts at the first open item. Each
completed item ships in the next tagged release.

**Core framework (released in v0.1.0)**

- [x] Projects, apps, typed settings, management commands, checks and development server
- [x] Routing with named URLs, request/response helpers and middleware
- [x] GORM models, recorded PostgreSQL migrations and typed query generation
- [x] Typed `.templ` components, Tailwind CSS and htmx
- [x] Forms, model forms, formsets and bounded uploads
- [x] Accounts, sessions, CSRF, password reset, groups and permissions
- [x] Static files, email, logging and application test helpers
- [x] Installable packages through public contracts
- [x] Published release with a [stability guarantee](https://cicadel.fauzaanu.com/en/0.2.0/releases/releases/index.md#stability-guarantee)

**Open core gaps (in order)**

1. [x] Reusable pagination with page links and a component (SVC-06) — v0.2.0, [guide](https://cicadel.fauzaanu.com/en/0.2.0/howto/pagination-and-messages/index.md)
2. [x] Flash messages: consume-once, levels, session-backed, rendered by a component (SVC-07) — v0.2.0, [guide](https://cicadel.fauzaanu.com/en/0.2.0/howto/pagination-and-messages/index.md)
3. [ ] Security headers and HTTPS policy defaults: HSTS, CSP and proxy handling (SEC-03)
4. [ ] Signed, expiring tokens with key rotation (SEC-04)
5. [ ] Transaction post-commit hooks (DB-03)
6. [ ] Typed per-package settings contract (DEV-04)

**After the core** — package-system completion and module extraction, a wider
migration operation subset, then extras: administration, cache and task backends,
sitemaps and managed redirects.

## Package system progress

The package foundation is working. The full reusable-app battery remains open.

- [x] Define manifests, API compatibility, dependency bounds and collision checks.
- [x] Integrate namespaced commands, configuration checks and owned resources.
- [x] Run startup and cleanup in dependency order, including failed initialization.
- [x] Integrate package migrations without deleting data on package removal.
- [x] Generate independent modules with `startpackage`.
- [x] Verify installation, upgrades and removal in a generated host.
- [x] Publish package static files through typed `App.Static` with hashed URLs, CDN prefixes and `collectstatic` ([guide](https://cicadel.fauzaanu.com/en/0.2.0/howto/static-files/index.md)).
- [ ] Finish typed contribution contracts across the full package surface. Package settings and event hooks remain.
- [ ] Extract remaining first-party batteries into independent modules.
- [x] Verify an external translation extension through public hooks.
- [x] Verify a second external package combining components/assets, commands and migration upgrade/removal behavior.

[Detailed acceptance checklist →](https://cicadel.fauzaanu.com/en/0.2.0/sources/batteries.md#package-system-acceptance-checklist)

<details>
<summary><strong>Migration progress and boundaries</strong></summary>

- [x] Separate migration generation from execution; no startup `AutoMigrate`.
- [x] Discover explicitly registered models across files and packages.
- [x] Record deterministic historical state and generate reviewable SQL.
- [x] Support declared schema alterations, data operations and dependency graphs.
- [x] Check history integrity and support documented concurrent-index recovery.
- [x] Verify clean installs, upgrades and data preservation on PostgreSQL.
- [x] Publish a versioned release and durable compatibility guarantees ([data guarantee](https://cicadel.fauzaanu.com/en/0.2.0/releases/releases/index.md#stability-guarantee)).

Advanced indexes, native enum/domain lifecycle and implicit join generation are outside inferred operations. Other database backends are excluded, not pending.

[Supported operations](https://cicadel.fauzaanu.com/en/0.2.0/ref/migrations/index.md) · [Verification record](https://cicadel.fauzaanu.com/en/0.2.0/sources/docs/automated-migrations-progress.md) · [Typed query generation](https://cicadel.fauzaanu.com/en/0.2.0/ref/querygen/index.md)

</details>

## Release gates

- [x] Document current APIs, tutorials and release policy.
- [x] Establish release automation and private security reporting.
- [x] Define the [stability guarantee](https://cicadel.fauzaanu.com/en/0.2.0/releases/releases/index.md#stability-guarantee) and public API surface.
- [x] Publish v0.1.0 and v0.2.0.
- [ ] Close the open core gaps above and release each one.

An independent security audit and external beta adoption are not release gates
(owner decision, 2026-11-10). Security features are covered by automated tests.

[Releases and stability](https://cicadel.fauzaanu.com/en/0.2.0/releases/releases/index.md) · [Changelog](https://cicadel.fauzaanu.com/en/0.2.0/releases/changelog/index.md)

## Tracking rules and scope

- [batteries.md](https://cicadel.fauzaanu.com/en/0.2.0/sources/batteries.md) owns full capability status and support decisions; [PLAN.md](https://cicadel.fauzaanu.com/en/0.2.0/sources/PLAN.md) records implementation milestones.
- Mark work complete only with documented boundaries and linked verification evidence. A dependency or example alone does not complete a battery.
- Keep this summary aligned with those trackers when a feature changes. No overall completion percentage is claimed: the workstreams differ in size and scope.
- PostgreSQL is the only supported database. Native i18n/l10n, GIS and other explicitly excluded ecosystem features remain third-party concerns.
- Released APIs follow the [stability guarantee](https://cicadel.fauzaanu.com/en/0.2.0/releases/releases/index.md#stability-guarantee); unreleased work on `main` may still change.