guilan-ace-deployment/tasks/plan.md

# Guilan ACE redesign and public-content CMS: implementation plan

**CMS course correction (2026-09-27):** The owner replaced this document's draft/publish and flexible-section proposals with the [simple direct-save CMS plan](bundle1-simplification-plan.md). Follow that plan and the updated [checklist](todo.md) for all CMS work. The original decisions below remain historical context for the broader redesign, not active CMS requirements.

Status: Bundle 0 discovery and design contract approved by the owner on 2026-09-26; product implementation has not started. This plan is shared across the frontend, backend, and deployment repositories. The executable checklist is [todo.md](todo.md). Later implementation checkpoints and production rollout approvals remain required.

## Outcome and boundaries

Redesign the public experience in this order: Home/About, authentication, events and registration, blog, then the staff-facing frontend admin. Build a Django-admin-managed content system for public editorial copy, shared identity/logo, approved images, navigation, footer/contact information, and page SEO. Editors may change bounded text in predefined Home/About sections and reorder or hide optional About sections; the owner-specified Home sequence remains fixed, and new layouts are developer work. Existing event, registration, payment, cancellation, and eligibility rules remain unchanged in the first release. Functional form labels, validation messages, permission-sensitive controls, and the staff-admin interface text remain versioned application code. Transactional email/SMS/in-app templates are a separate later phase.

The official association name is `انجمن علمی مهندسی کامپیوتر دانشگاه گیلان (دانشکده‌ی فنی و مهندسی شرق گیلان)`. Use it in official metadata and About identity; the owner approved the shorter header lockup, `انجمن علمی مهندسی کامپیوتر` with a faculty subline, in the logo-led visual direction. Preserve the recognizable existing logo until an approved replacement is supplied.

## Existing-system facts that shape the work

- Frontend: Next.js 15, React 18, Tailwind 3, Radix UI, Persian RTL. Main surfaces include `src/views/Home.tsx`, `AboutUs.tsx`, `Auth.tsx`, `Events.tsx`, `EventDetail.tsx`, `Blog.tsx`, and `Admin*` views. Home and About currently contain public copy, contact data, and SEO strings in code; About contains contradictory names, email/social links, and unverified numeric claims. Shared navigation/footer also contain static public content.
- Backend: Django 5, Ninja API, PostgreSQL, Django Unfold admin, Redis/Celery. Events, blog, gallery, and announcements already have domain models; there is no public-page CMS. Event-specific success copy is already data-backed, and should not be duplicated in the new CMS.
- Deployment: Docker Compose runs the backend without an automatic `migrate` step; PostgreSQL and Django media are backed up. Schema migration, media staging, and content seeding therefore need explicit, separately verified release operations.
- The blog was recently redesigned. Audit it for coherence and accessibility before replacing components wholesale.

## Decisions and proposed contracts

1. **Public-only content boundary.** Inventory every public route and classify strings as editorial/brand/SEO, domain data, or functional UI. Only the first category moves into the CMS. Homepage/About sections use a finite, documented type registry; no arbitrary HTML or general-purpose page builder.
2. **Publishing workflow.** Designated staff can save drafts and preview; a narrower publisher group can publish/restore a previous published revision; superusers retain full access. Public API returns only published revisions. A draft may never become visible through a cache, preview URL, or guessed identifier. Audit who changed and published each revision.
3. **Typed content model.** A site identity/settings record holds official/short names, logo, approved contact/social links, footer, and SEO defaults. Public editorial pages have stable slugs (at least `home`, `about`, `events`, and `blog`, plus any other editorial surface found in inventory). Home/About have ordered/visible sections with approved section types; simpler route introductions and SEO use bounded fields. Prefer typed fields/validated schemas over opaque, unbounded JSON. Individual events/blog posts stay in their domain tables.
4. **Public and preview APIs.** Add a versioned, read-only published-content endpoint with an explicit response schema and safe cache policy. Draft preview requires staff authentication and is `no-store`; publish should invalidate or quickly expire public caches. Frontend renders public content server-side where SEO needs it, with safe fallback during rollout; no permanent duplicate copy after cutover.
5. **Images and copy.** Logos/photos are managed files with alt text, dimensions/size limits, and a documented license/approval source. Prefer actual association/campus/event material, strong Persian typography, and clear information architecture over generic gradients, fabricated stats, decorative 3D, or motion that impedes tasks. Respect `prefers-reduced-motion` and keep admin interaction mostly motion-free.
6. **Incremental release.** Ship backend CMS and verified seed first behind the existing frontend. Switch Home/About via a reversible feature flag. Then release auth, events, blog, and frontend admin as independently testable slices. New CMS data must not alter registration or payment state.

## Design process and approval gates

Use the repository-local Impeccable workflow, **visual review before UI implementation**: review `PRODUCT.md`, compare the current Home/About with real mobile/desktop captures, and use the owner-provided references to refine the current site. Three earlier concepts were rejected by the owner on 2026-09-25; the owner approved the logo-led Home and About visual direction on 2026-09-25. Home follows the owner's order: introduction, featured events, featured blog posts, CTA, footer. Shadcn/ui and Lucide are the implementation component system; the logo supplies teal, pale gold, and charcoal. The approved direction is recorded in `DESIGN.md`; the owner approved the T05 CMS/API contract and Checkpoints A/B on 2026-09-26. Start with existing approved logo, event posters, and other available real assets; new association photography is not a dependency. Run the installed Impeccable hooks during design work; after cloning, developers must trust/enable project hooks in Codex (`/hooks`) for their environment. Hooks are review aids, not substitutes for human design and accessibility review.

Design acceptance is based on actual tasks and content: a student finds the next event, understands eligibility/cost, completes registration, and sees a trustworthy success/payment state; a visitor learns who the association is; a staff editor publishes safely. Test Persian line breaks, mixed-script dates/numbers, 320–1440px widths, keyboard navigation, contrast, reduced motion, loading/empty/error states, and realistic long content.

## Phase order and effort

Effort is person-days for one experienced full-time developer/designer with normal stakeholder review. It includes design, implementation, tests, and rework; it is not elapsed time from merely installing skills. Overlap is possible after the CMS contract is approved, but the requested release priority is preserved.

| Phase | Scope | Effort | Exit gate |
| --- | --- | ---: | --- |
| 0. Discovery and design contract | Content inventory, facts/assets, flow map, Impeccable concept approval | 4–5 d | Approved content matrix, Home/About direction, baseline captures |
| 1. CMS foundation and migration | Model, roles, admin editing, published/preview APIs, seed and dry-run | 9–12 d | Published content matches approved inventory; no draft leak |
| 2. Home/About and shared shell | Design system, pages, header/footer, responsive/SEO integration | 9–12 d | Edited content appears correctly at all target widths |
| 3. Authentication | Login/signup/verification/reset/Google callback states, recovery UX | 5–7 d | Existing auth behavior preserved, end-to-end tests pass |
| 4. Events and registration | Listing, details, free/paid journeys, payment/success states | 9–12 d | Existing event rules preserved and state matrix passes |
| 5. Blog | Cohesion audit, selective refinement, reading/discovery | 4–6 d | Current blog capabilities and URLs preserved |
| 6. Frontend staff admin | Navigation, tables/forms, role clarity, mobile usability | 7–10 d | Essential staff tasks work at phone and desktop widths |
| 7. Release hardening | Cross-browser/a11y/performance regression, deploy rehearsal, launch | 4–7 d | Backup, smoke, rollback, and owner sign-off |
| **Total** | | **51–71 person-days** | **About 11–15 calendar weeks for one full-time person**, allowing reviews |

Two developers with clear frontend/backend ownership could shorten calendar time, but not person-days proportionally; shared design/API decisions and release testing remain on the critical path. Unapproved assets, conflicting content facts, or additional business-rule changes increase the estimate.

## Production content migration and cutover

1. **Freeze and inventory.** Capture the current production pages and code strings into a versioned content manifest with stable keys, source path, intended destination field, exact text, image path/checksum, and an approval status. Separate existing domain data from static editorial text. Mark disputed contacts, affiliated-association claims, counts, and old links for owner approval; do not silently “correct” them.
2. **Build schema and tests.** Add additive CMS tables and role permissions. Do not drop old columns or repurpose event/blog data. Test migration on an anonymized production-sized database copy, including repeated deploy/seed runs and Unicode/RTL content.
3. **Prepare assets.** Stage approved logo and other source images into backed-up Django media, record checksums, dimensions, alt text, and target CMS records. Never reference a frontend build path as a permanent media source. Unapproved imagery may remain absent; layout must handle it.
4. **Dry-run seed.** Provide a versioned, idempotent import command that prints create/update/skip/conflict counts and a field-level diff. It must refuse to overwrite any editor-modified content by default. Use stable keys and a seed version, log outcomes, and support a no-write validation mode. Seed approved snapshots as drafts first; publisher reviews and publishes. A Django data migration may create immutable baseline records, but media transfer and editorial approval remain explicit operations, not filesystem side effects inside a schema migration.
5. **Production gate.** Take and verify fresh database/media backups. Deploy backend compatible with the old frontend, run `migrate` explicitly, stage media, run seed dry-run, review conflicts, then execute seed and validate API/draft permissions. This can occur before the UI cutover with no public visual change.
6. **Switch and observe.** Deploy frontend with CMS reads behind a flag; compare rendered copy and SEO against approved manifest, test mobile/desktop and all key journeys, then switch Home/About. Monitor CMS API errors, missing media, cache staleness, and registration/payment signals before advancing to later slices.
7. **Rollback.** For a frontend/content regression, disable CMS rendering or restore the previous frontend image and republish the prior content revision. Keep additive CMS tables and original content until the new path is stable. Database restore is a last-resort incident procedure because it can erase registrations/payments created after the backup; decide on it with an incident owner, never as the routine rollback.

## Verification and definition of done

Every task in `todo.md` has explicit acceptance and verification. At each checkpoint run backend focused tests and `python manage.py test --settings=config.settings.test`, frontend `npm run lint` and `npm run build`, then browser checks on desktop/mobile and reduced-motion/keyboard modes. Add automated tests for CMS permission, draft isolation, seeding idempotency, page content API, event/auth state-preservation, and critical browser journeys. Measure accessibility and route bundle/performance against a captured baseline rather than an invented target; budget regressions deliberately. Check Persian content with a human reviewer. A release is done only after stakeholder approval, backup restore rehearsal, documented rollback, and verified production smoke tests.

## Risks and decisions still requiring approval

- **Contacts and factual claims:** The owner selected the About-page email, Instagram, and Telegram entries on 2026-09-24. The other legacy variants remain in the inventory. Address, phone, statistics, and affiliated-association claims still need entity/currentness review before production seed publication.
- **Approved imagery:** Existing recognizable logo and approved current assets are the baseline. Catalog their usage rights; do not generate substitute “association photos.”
- **Editorial ownership:** Nominate actual staff and publisher accounts/group membership before rollout; document the review/restore procedure.
- **Scope guard:** Transactional messaging templates and changes to event/payment business logic require a separately approved specification and estimate.