Development

This page is for people working on cr4te itself.

Install for Development

git clone https://github.com/vger-6/cr4te.git
cd cr4te
pip install -e ".[dev]"

Browser tests need the browser-test extra and Playwright browser setup:

pip install -e ".[browser-test]"
python -m playwright install chromium

Run Tests

Unit tests:

python -m unittest discover tests

Focused tests:

python -m unittest tests.test_metadata_manager
python -m unittest tests.test_html_build
python -m unittest tests.test_media_staging

Rendered-site browser tests build the bundled example library, serve the generated HTML from a temporary local HTTP server, and exercise JavaScript behavior on the fully rendered pages:

python -m unittest discover tests_browser

Architecture Map

Important modules:

• cr4te.py: CLI entry point, validation, confirmation, and process exit outcomes.
• build_runner.py: build-phase orchestration, timing, and expected operational failure context.
• config_manager.py: default config, user config loading, CLI overrides.
• config_presets.py: domain presets.
• metadata_manager.py: creates and reconciles editable metadata files.
• library_scan.py: scans folders and buckets media.
• library_builder.py: builds typed creator/project models and lightweight library indexes.
• library_issues.py and build_issues.py: best-effort and strict issue handling.
• html_builder.py: streaming/two-pass HTML build.
• page_contexts.py and overview_contexts.py: typed render context assembly.
• render_assets.py: thumbnails and media staging.
• render_media.py: media section context assembly.
• render_metadata.py: metadata display entries and filter links.
• template_renderer.py: Jinja rendering boundary.
• templates/: generated HTML templates.
• assets/: static CSS, JS, and favicon copied into output.

Build Pipeline

cr4te build runs roughly as:

1. Load config and apply CLI overrides.
2. Validate paths and request output-folder confirmation.
3. Discover themes.
4. Clear or create the output folder.
5. Reconcile metadata files.
6. Build a lightweight library index.
7. Render one creator at a time.
8. Render overview and tag pages.
9. Combine and deduplicate phase issues.
10. Log the final build summary.

The streaming/two-pass shape matters for larger libraries. Avoid changes that require holding all full media groups for the whole library globally.

Product Requirements

Durable product/design requirements live in info/REQUIREMENTS.md in the main repo.

Frontend Contracts

The generated site is static. Feature scripts register with cr4te.onReady; templates should not use inline JavaScript handlers.

Client-side features include:

• Search filtering
• Pagination
• Aspect and justified gallery layout
• Theme selector
• Lightbox
• Audio player
• Video player
• Responsive content movement

Documentation Notes

Keep the README as the repository front door and the wiki as the manual. When wiki pages change substantially, check whether the README should link to them or shed duplicated detail.