Home Information - Your home, your data, organized.
Profile Management
Overview
Profiles are predefined configurations that create a fully populated Home Information setup — Locations with background SVGs, LocationViews with zoom/pan settings, Entities with positions, and Collections. They provide the first-time user experience when a user selects a home type (Single Story, Two Story, Apartment) on the welcome page.
Profile Structure
JSON Format
Profile data is stored as JSON files in src/hi/apps/profiles/assets/profiles/. Each file defines a complete set of Locations, Entities, and Collections.
The field constants for the JSON structure are defined in src/hi/apps/profiles/constants.py. The JSON structure follows this hierarchy:
profile
├── locations[]
│ ├── svg_template_name → references a background template
│ └── views[] → LocationViews with zoom/pan/rotate settings
├── entities[]
│ ├── positions[] → placement on specific Locations
│ ├── paths[] → SVG paths on specific Locations
│ └── visible_in_views[] → which LocationViews show this entity
└── collections[]
├── entities[] → entity names in this collection
├── positions[] → collection positioning
└── visible_in_views[] → which LocationViews show this collection
SVG Template References
Each Location in the profile JSON has a svg_template_name field that references a Django template in the backgrounds directory (see SVG Background System for template details). At profile load time, the template is rendered, processed, and written to MEDIA_ROOT. The viewBox is extracted from the rendered SVG — it is not stored in the JSON.
Profile Types
Profile types are defined in src/hi/apps/profiles/enums.py (ProfileType enum). Each type maps to a JSON file via the json_filename() method.
Profile Loading
Profile loading is handled by ProfileManager in src/hi/apps/profiles/profile_manager.py. The load process:
- Load the JSON file for the selected profile type
- Render SVG background templates and write to MEDIA_ROOT (
_render_svg_templates) - Create Location and LocationView database objects
- Create Entity objects with positions and paths
- Create Collection objects with entity assignments and positioning
- Set up entity and collection visibility in LocationViews
The _render_svg_templates method uses LocationManager.render_svg_template_to_media() which renders the Django template, runs it through the SVG processing pipeline, and writes the fragment to MEDIA_ROOT. The rendered filename and extracted viewBox are stored as temporary fields on the location data dict for use during Location creation.
Error Handling
ProfileManager has both strict (load_profile) and robust (load_profile_robust) loading modes. The robust mode tracks statistics via ProfileLoadingStats and continues past individual failures, useful for development and testing.
Creating a New Profile
Workflow
The goal is to arrive at a fully configured database state that can be captured as a new profile. How you populate the data is flexible — the snapshot tool captures whatever is in the database.
The typical workflow:
- Start with an empty database — delete existing data or use a fresh database.
- Choose "Start with an empty layout" on the welcome page. This puts you in edit mode with a blank Location.
- Create the background SVG for the first Location using the background editor. Use the palette to draw walls, floors, doors, windows, etc.
- Add more Locations if needed (e.g., second floor, attic, basement). Each gets its own background SVG.
- Set up LocationViews for each Location — configure zoom, pan, and rotation for different viewing perspectives (e.g., "Interior", "Exterior", "Kitchen").
- Add Entities — create all the entities that should be part of this profile. Position them on the appropriate Locations and assign them to LocationViews.
- Add Collections — group entities into collections, position collections, assign visibility.
- Generate the snapshot using the Profile Snapshot Generator (see below). Write to
/tmpfirst for review. - Register the profile type — add a new value to the
ProfileTypeenum if this is a completely new profile type. - Commit — once verified, generate with
output_to_tmp=Falseto write the real profile files, then commit.
Updating an Existing Profile
Workflow
When updating an existing profile, you want to start from the current profile state, make modifications, and re-capture.
- Start with an empty database — delete existing data or use a fresh database.
- Choose the profile to update on the welcome page (e.g., "Single Story"). This loads the existing profile with all its Locations, Entities, and Collections.
- Modify as needed — edit backgrounds, reposition entities, add/remove items, adjust views. The existing profile gives you the starting point so you only change what needs changing.
- Generate the snapshot — this captures the modified state. The SVG template reconciliation will match unchanged backgrounds to their existing templates and create new template files for any backgrounds you edited.
- Review — check the JSON and any new SVG template files in
/tmp. - Commit — generate with
output_to_tmp=Falseand commit.
Profile Snapshot Generator
The snapshot generator captures the current database state into a profile JSON file. It lives at src/hi/apps/profiles/tests/devtools/profile_snapshot_generator.py.
Usage
From the Django shell:
from hi.apps.profiles.tests.devtools.profile_snapshot_generator import ProfileSnapshotGenerator
from hi.apps.profiles.enums import ProfileType
generator = ProfileSnapshotGenerator()
# Write to /tmp for review (safe — doesn't modify real profile files)
output_path = generator.generate_snapshot(ProfileType.SINGLE_STORY, output_to_tmp=True)
# Write directly to the real profile location (overwrites existing)
output_path = generator.generate_snapshot(ProfileType.SINGLE_STORY, output_to_tmp=False)
SVG Template Reconciliation
When generating a snapshot, the generator must determine which background template each Location corresponds to. The Location model only stores a MEDIA_ROOT filename — there's no record of the originating template.
The generator handles this by comparing the Location's SVG fragment content against all rendered background templates:
- Match found: The JSON references the matched template name.
- No match: The SVG has been customized. The generator creates a new template file by wrapping the fragment in an
<svg>element with the viewBox and saving it to the backgrounds template directory (or/tmpifoutput_to_tmp=True).
This is implemented in _reconcile_svg_templates() in the snapshot generator.
Review Checklist
After generating a snapshot:
- Review the JSON — check the output file for correctness. Verify
svg_template_namefields reference valid templates. - Review new SVG templates — if the generator created new template files, open them in a browser to verify they render correctly.
- Test the round-trip — load the generated profile on a fresh database to verify it produces the expected result.
Key Files
| File | Purpose |
|---|---|
src/hi/apps/profiles/profile_manager.py |
Profile loading logic |
src/hi/apps/profiles/constants.py |
JSON field name constants |
src/hi/apps/profiles/enums.py |
ProfileType enum |
src/hi/apps/profiles/assets/profiles/*.json |
Profile JSON data files |
src/hi/apps/profiles/tests/devtools/profile_snapshot_generator.py |
Snapshot generation tool |
src/hi/apps/profiles/templates/profiles/svg/backgrounds/ |
Background SVG templates |
src/hi/apps/location/location_manager.py |
SVG template rendering to MEDIA_ROOT |
src/hi/apps/common/svg_utils.py |
SVG processing pipeline |