Manuals App — Change Log¶
This log tracks software changes for the Manuals backend app.
App metadata¶
| Field | Value |
|---|---|
| Primary code location | /reflux/backend/manuals/ |
| Related APIs | /manuals/, /chapters/, /media/, /callouts/, /categories/, /topics/ |
| Last updated | 2026-04-17 |
Current status¶
| Item | Status | Notes |
|---|---|---|
| Active development | In progress | Ongoing refactor into models / serializers / services / views / admin structure |
| Next release target | TBA | |
| Known risk | Medium | Refactor is broad, but architecture is now much cleaner and more explicit |
Recent changes (newest first)¶
| Date | Type | Summary | Impact | Reference |
|---|---|---|---|---|
| 2026-04-17 | Feature | Introduced capability-based permissions layer for Manuals (view/manage/export/download separation) | High | |
| 2026-04-17 | Test | Added API permission tests for manuals, chapters, media, and download endpoints | Medium | |
| 2026-04-17 | Feature | Added audit logging for manuals, chapters, and media lifecycle events (create/update/delete) | Medium | |
| 2026-04-17 | Test | Added API-level audit logging tests for manuals, chapters, and media endpoints | Medium | |
| 2026-04-17 | Fix | Introduced dedicated ChapterWriteSerializer to fix chapter creation bug (missing manual_id) | Medium | |
| 2026-04-17 | Fix | Corrected JSON-based media cleanup so deleting one section media item removes only its stale inline TipTap reference and preserves other valid inline media blocks | Medium | |
| 2026-04-17 | Test | Added coverage for section media cleanup scenarios: referenced media deletion, unreferenced media deletion, and non-section media deletion | Medium | |
| 2026-04-17 | Refactor | Split monolithic files into structured folders (models/, serializers/, services/, views/, admin/, signals/) | Medium | |
| 2026-04-17 | Refactor | Split model layer into domain-focused modules (taxonomy, manuals, content, callouts, media, items) | Medium | |
| 2026-04-17 | Refactor | Split serializer layer into concern-based modules and removed duplicated serializer definitions | Medium | |
| 2026-04-17 | Refactor | Split views into dedicated modules for taxonomy, manuals, chapters, callouts, media, and downloads | Medium | |
| 2026-04-17 | Refactor | Expanded Django admin into structured modules with previews, inlines, counts, and better org-aware management | Low | |
| 2026-04-17 | Refactor | Moved file lifecycle cleanup into dedicated signals package and reduced duplication in file cleanup handlers | Low | |
| 2026-04-17 | Refactor | Extracted media cleanup logic into services layer | Medium | |
| 2026-04-17 | Refactor | Centralized nested write logic (chapters/items/steps) in serializer + service workflows | Medium | |
| 2026-04-17 | Feature | Added PDF export endpoint using WeasyPrint | Low | |
| 2026-04-17 | Feature | Added embed-based query optimization for manual detail endpoints | Medium | |
| 2026-04-17 | Performance | Optimized queryset prefetching for deep manual structures | Medium | |
| 2026-04-17 | Refactor | Introduced ChapterItem as unified display stream model | High | |
| 2026-04-17 | Feature | Added inline media synchronization for Tiptap content | Medium |
Open items and status¶
| ID | Title | Status | Priority | Owner | Target | Reference |
|---|---|---|---|---|---|---|
| MANUALS-001 | Move remaining manual create/update orchestration fully into top-level service functions | Open | P1 | Unassigned | TBA | |
| MANUALS-003 | Introduce caching for manual detail endpoint | Open | P2 | Unassigned | TBA | |
| MANUALS-005 | Extend audit logging coverage (sections, callouts, step groups, reorder flows) | In progress | P2 | Unassigned | TBA | |
| MANUALS-006 | Add dedicated tests for nested chapter/item sync edge cases | Open | P2 | Unassigned | TBA |
Known bugs¶
| ID | Symptom | Severity | Status | Workaround | Reference |
|---|---|---|---|---|---|
| BUG-MANUALS-001 | ChapterItem ordering may become inconsistent under concurrent reorder/update operations | Medium | Open | Retry update | |
| BUG-MANUALS-002 | Nested merge/replace flows may still need stronger regression coverage for complex mixed content payloads | Medium | Open | Re-save or retry with simpler payload |
Breaking changes and migrations¶
| Date | Change | Action required | Reference |
|---|---|---|---|
| 2026-04-17 | Serializer structure split into modules | Update import paths | |
| 2026-04-17 | Model layer split into module package | Update direct model import paths if importing submodules explicitly | |
| 2026-04-17 | Views split into module package | Update direct view import paths if importing submodules explicitly | |
| 2026-04-17 | Introduced capability-based permissions layer (CanViewManuals / CanManageManuals / etc.) | Ensure all custom views apply correct permission classes | |
| 2026-04-17 | ManualDetailSerializer write behavior updated (chapters_write / callouts_write) |
Adjust API payload format if needed | |
| 2026-04-17 | Media cleanup moved to services layer and section cleanup now targets description_json instead of legacy HTML assumptions |
Ensure delete workflows use service cleanup helpers |
Notes¶
Major refactor direction¶
The Manuals app is transitioning to a clean architecture:
- models → data structure
- serializers → validation + API shaping
- services → orchestration and business logic
- views → HTTP layer
- signals → low-level file lifecycle cleanup
- admin → operational content management
ChapterItem design decision¶
ChapterItem introduces a stream-based rendering model, allowing:
- flexible ordering of content
- mixed content types (sections, notes, step groups, callouts, media grids)
- future extensibility for new item kinds
Permissions layer introduction¶
A capability-based permission system has been introduced:
- separates view / manage / export / download concerns
- fully org-scoped via
HasCurrentOrg - aligned with core permission helpers
- enforced consistently across all endpoints
This significantly improves:
- security boundaries
- clarity of access rules
- future extensibility
Media handling strategy¶
Media is:
- attached to multiple parent types
- validated at upload time
- cleaned up via:
- signals (file lifecycle)
- services (content reference cleanup)
Current stability note¶
The app structure is now significantly cleaner than before:
- duplicated serializer code removed
- views split by concern
- admin expanded
- file cleanup isolated
- JSON-based media cleanup fixed
- permissions centralized
Future direction¶
- finalize audit coverage across all content types
- improve concurrency handling
- introduce caching for large manuals
- expand regression testing for nested updates
- explore versioning / history tracking
Summary¶
The Manuals app is in an active refactor and stabilization phase focused on:
- modular architecture
- maintainability
- correctness of nested content behavior
- safer media handling
- strong permission boundaries
- improved developer experience
Immediate next focus areas:
- deeper test coverage
- orchestration cleanup into services
- concurrency hardening
- audit expansion