Manuals¶

Purpose¶

The manuals app provides a structured content system for building and managing internal manuals.

It supports:

manual taxonomy
manual and chapter management
ordered chapter content streams
rich content sections
notes
step-by-step instructions
callouts
attached media
PDF export

It acts as a content-authoring and delivery layer for operational knowledge.

Typical use cases include:

technician instructions
process documentation
onboarding manuals
safety procedures
maintenance guides
customer-facing or externally shareable manuals

Key concepts¶

Category¶

A top-level taxonomy bucket for manuals.

Used to group manuals by broad domain.

Examples:

Operations
Safety
Training
Maintenance

Categories are org-scoped.

Topic¶

A second taxonomy layer for manuals.

Topics allow more flexible grouping and can include presentation metadata such as color.

Examples:

Electrical
Inspection
PPE
Installation

Topics are org-scoped.

Manual¶

The main top-level content object.

A manual contains:

title
description
optional cover image
category
topic
publishing state
ordered chapters

A manual belongs to exactly one org.

Chapter¶

A manual is divided into ordered chapters.

A chapter contains:

title
description
optional cover image
ordered content items
related media
related callouts

Chapters are the main container for structured content blocks.

Section¶

A section is a rich content block inside a chapter.

It contains:

title
optional plain description
description_json rich content document

Sections may also contain:

media
callouts

Sections are intended for explanatory or descriptive content.

SectionNote¶

A lightweight note block inside a chapter.

It contains:

title
body

Notes are useful for quick reminders, warnings, or supplementary text.

StepGroup¶

A step group is a container for ordered instructional steps.

It contains:

title
ordered ManualStep rows

Step groups are intended for procedural content such as workflows or checklists.

ManualStep¶

A single ordered step inside a step group.

It contains:

title
body text

A step may also have:

media
callouts

CalloutPreset¶

A reusable presentation preset for callouts.

It defines:

name
slug
icon
color
order
active state

Callout presets allow consistent visual language across manuals.

Callout¶

A callout is a highlighted informational block.

It may be attached to exactly one parent:

manual
chapter
section
step group
step

A callout can either use its own icon/color or inherit from a preset.

Typical callout examples:

Warning
Tip
Important
Safety notice

ManualMedia¶

A media attachment used inside manuals.

Media may be attached to exactly one parent:

manual
chapter
section
step group
step

Supported media types:

image
video
file

ChapterItem¶

A chapter item defines the ordered display stream for chapter content.

Supported item kinds:

section
note
callout
step_group
media_grid

This model is important because it separates:

stored content objects
display order within the chapter

That makes chapters more flexible and composable.

Entry points¶

API endpoints¶

The app exposes endpoints for:

categories
topics
manuals
chapters
callout presets
callouts
manual media
cover/media downloads
manual PDF export

These endpoints are split across dedicated view modules under:

views/taxonomy.py
views/manuals.py
views/chapters.py
views/callouts.py
views/media.py
views/downloads.py

Admin¶

The Django admin provides management interfaces for:

taxonomy
manuals
chapters
sections
notes
step groups
steps
callouts
presets
media
chapter items

The admin is intended to support both:

inspection
direct manual maintenance

Signals¶

Signals are used for file lifecycle cleanup.

Current signal responsibilities include:

deleting file objects when related rows are deleted
deleting replaced cover images when a new file is saved

These are infrastructure-level signals, not business workflow signals.

Services¶

The services layer contains manual-specific orchestration and helper logic.

Current service areas include:

manuals
chapters
sections
callouts
media
PDF generation
shared helpers

This is where nested content synchronization and cleanup logic should live.

Dependencies¶

Depends on¶

The manuals app depends on:

core
timestamp base models
storage helpers
upload validation
org-scoped policy helpers
orgs
organization ownership
Django / DRF
ORM
serializers
viewsets
admin
WeasyPrint
PDF export

Used by¶

The manuals app is primarily a standalone content app, but it can support:

internal operations workflows
training systems
field technician interfaces
customer documentation delivery
future external publishing flows

Operational notes¶

Known pitfalls¶

Nested content writes are complex¶

Manual creation and update can involve:

chapters
chapter items
sections
notes
step groups
steps
callouts

This means nested sync logic must stay centralized and carefully tested.

ChapterItem drives display order¶

Content objects alone do not define rendering order.

The actual chapter stream is controlled by ChapterItem.

If ChapterItem rows are incorrect or incomplete, chapter output can become inconsistent.

Parent attachment rules matter¶

Both Callout and ManualMedia are designed to attach to exactly one parent.

Incorrect parent handling can create ambiguous content placement.

Rich section content uses JSON¶

Section.description_json is the current rich-text source of truth.

Any cleanup or media synchronization must work against that JSON structure, not older HTML-based assumptions.

File lifecycle must stay safe¶

Manual covers, chapter covers, and media files must be cleaned up correctly when:

rows are deleted
files are replaced

This is currently handled via signals and should remain infrastructure-safe.

Performance considerations¶

Deep manual retrieval can become heavy¶

Detailed manual retrieval can include:

chapters
items
sections
notes
step groups
steps
media
callouts

This requires careful queryset optimization and prefetching.

Admin pages can become relationship-heavy¶

Because of the number of nested relations, admin configuration should prefer:

select_related
prefetch_related
autocomplete_fields

where appropriate.

PDF export is rendering-heavy¶

PDF export builds a full HTML representation and renders it with WeasyPrint.

This can become expensive for very large manuals.

Design characteristics¶

The manuals app is designed to be:

org-scoped
structured
ordered
media-aware
reusable
authoring-friendly
presentation-friendly

It separates:

content storage
display order
file attachments
visual callouts
taxonomy
export behavior

This makes it flexible enough for both simple and highly structured manuals.

Suggested internal structure¶

The current cleaned structure should follow these boundaries:

Models¶

taxonomy
manuals and chapters
content blocks
callouts
media
ordered chapter items

Serializers¶

taxonomy serializers
media serializers
callout serializers
section/step serializers
chapter/manual serializers

Services¶

nested manual sync
chapter/item sync
media cleanup
section inline-media cleanup
PDF generation

Views¶

taxonomy endpoints
manual endpoints
chapter endpoints
callout endpoints
media endpoints
download endpoints

Signals¶

file cleanup only

Summary¶

The manuals app is a structured documentation and instructional content system.

It provides:

taxonomy for organizing manuals
manuals and chapters for top-level structure
content blocks for rich instructional content
media and callouts for presentation support
ordered chapter streams for flexible rendering
PDF export for offline distribution

It is best understood as a small content platform for operational knowledge, not just a single manual model.