๐งฑ Technology, Administration, and Reliability
Audience: Org Admin, Data Admin, System Admin, Deployment Administrator, Developer, Support
Related: Feature Catalog ยท AI Features ยท Database Administration ยท API Tester and Postman ยท Performance and Job Status
Blackcap's everyday features are backed by a substantial administration, diagnostics, data, and deployment foundation. These capabilities are not ordinary household workflows, but they make Blackcap safer to operate, easier to support, and practical to run on either a Raspberry Pi or GCP.
Access remains permission-aware. System-wide diagnostics and repair actions are restricted to System Admins, while organization and data tools remain limited to the roles that need them. The application continues to enforce organization scoping and endpoint permissions even when a technical page is visible.
Architecture at a glance
Blackcap keeps user interfaces, API clients, background work, persistence, provider integrations, and display delivery behind one permission-aware application model. The same architecture supports a Raspberry Pi appliance/server and a GCP deployment while allowing provider-specific database and infrastructure behavior where it is genuinely required. For implementation boundaries and route ownership, see Application Architecture.
๐ Organizations, permissions, and security
- Organizations are the primary tenant boundary for recipes, meal plans, shopping lists, inventory, displays, configuration, and activity.
- Role and permission checks distinguish System Admin, Org Admin, Data Admin, contributor/operator, and ordinary-user responsibilities.
- Internal login supports invitations, password reset, TOTP MFA, recovery codes, trusted browsers, and organization MFA policy.
- User-owned API Tokens are named, organization-aware credentials with show-once secrets, revocation, access attribution, and retention.
- CSRF protection, safe external fetch rules, request validation, encrypted or masked secrets, and audit records protect administrative workflows.
๐๏ธ Database Administration
Database Admin is a provider-aware technical workspace for both SQLite and PostgreSQL deployments. Depending on permission and provider, it includes:
- resource exploration with explicit relationships and organization context;
- schema export and provider-aware metadata;
- saved queries and guarded SQL Console behavior;
- data-problem detection, maintenance actions, and reconciliation tools;
- restore and repair diagnostics;
- database parity and schema-verification support; and
- controls that keep live writes separate from read-only inspection and audit work.
See Database Administration for the full resource, maintenance, SQL Console, and repair model.
๐งโ๐ป API Tester and API Tokens
API Tester opens against the current Blackcap instance and uses the registered route inventory rather than a disconnected static list. It supports:
- role-aware endpoint visibility and execution;
- the current authentication and organization context;
- sanitized request and response examples;
- option and identifier resolution for supported parameters;
- endpoint testing without requiring separate API software; and
- Postman export for broader integration development.
API Tester complements personal API Tokens. It does not bypass endpoint permissions, organization scoping, CSRF requirements, or token policy. See API Tester and Postman and API Development.
๐ฅ๏ธ System diagnostics and actions
The System page provides a deeper operational view than the quick About summary. Its capabilities include:
- application version and build identity;
- display mode, busy state, project/configuration paths, recipe count, and cloud-backup connection status;
- detected host, detection source, operating system, architecture, hardware model, container status, and Raspberry Pi capability hints;
- current uptime and recent reboot history with cautious reason confidence;
- bounded log viewing from fixed sources with severity/search filters and secret redaction;
- tracked Direct SQL Audit jobs for finding application code that bypasses the centralized database service;
- read-only Database Parity / Schema Verification and separately confirmed repair of registered safe additive gaps;
- e-ink refresh, render, deep-clean, and last-output diagnostics when attached hardware is available; and
- configuration export without exposing secret values.
Long-running audits are background jobs with queued/running/completed/failed state, progress, duration, and downloadable or inspectable results instead of blocking the page.
๐ Performance and background jobs
Blackcap records operational timing and job state so administrators can distinguish a slow request, a queued task, a provider delay, and a physical display refresh. Technical visibility includes:
- request and task duration trends;
- queue time, execution time, resource snapshots, and slow-request review;
- render and display-delivery phases;
- backup, email, purge, external-list, and provider timing;
- failed, retryable, reviewed, ignored, stale, and stoppable background work; and
- regression-to-regression performance comparisons.
See Performance and Job Status and Background Jobs.
โ๏ธ Backups, restore, and managed maintenance
Blackcap supports local and connected cloud backup destinations, provider-aware backup scope, restore staging, validation, rollback safety, retention, and cache reconstruction. The SQLite database can be included in a Pi backup, while GCP/PostgreSQL deployments keep Cloud SQL backup responsibility at the platform boundary.
Application startup and managed schedules also support idempotent database migrations, periodic backups, display-content refresh, Menu refresh, regression continuation, data purge, GeoIP updates, Letโs Cook watchers, and enabled panel maintenance. See Backups and Restore and Background Jobs and Schedules.
๐งน Data retention and cleanup
Data Cleanup applies domain-aware retention instead of issuing generic table deletes. Administrators can use dry-run and real-run workflows for generated artifacts, completed jobs, audit history, display assignment batches, recipe-share history, Letโs Cook detail/summary records, restore staging, and other bounded operational data.
Retention rules preserve active dependencies and organization boundaries. See Data Retention and Purge.
๐งช Regression testing and safe diagnostics
Blackcap includes an administrative regression harness for immediate, scheduled, resumable, and diagnostic-clone runs. Coverage can include role behavior, integrations, display assignment, database/service checks, and the same Direct SQL Audit and Database Parity / Schema Verification jobs exposed on System.
Diagnostic clones allow isolated reproduction without modifying the source organization. See Regression Testing and Diagnostic Clones.
๐ Audit, access, and support visibility
Technical administration also includes activity history, login and API Token access, display access breadth, voice activity, configuration changes, support-request diagnostics, country-level GeoIP lookup, and privacy-conscious instance reporting. These surfaces are designed to support troubleshooting without exposing raw secrets or unnecessary personal data.
See Audit, Access Activity, and Logging, GeoIP and Access Location, Support Requests, and Instance Reporting.
๐ Deployment foundation
Blackcap maintains two primary server paths:
- Raspberry Pi: SQLite by default, optional attached e-ink hardware, stunnel TLS, systemd services, managed schedules, and optional Remote Pi Client behavior.
- GCP: Compute Engine, Cloud SQL PostgreSQL, Cloud SQL Auth Proxy, Gunicorn, Nginx, HTTPS certificates, managed services, and browser or remote-client display delivery.
Customer deployments can also be delivered through Microwave Pie Packages. A Package is associated with one Microwave Pie License and one intended installation, while the reusable Application Release behind it can be either Source / uncompiled or Compiled. Both package formats install immutable release provenance including the exact full Git SHA, deployment mode, platform, Package/Release references, and the application version. The signed License remains the application-use entitlement; the Package controls delivery/provenance and does not replace licensing.
Package-managed installations expose System โ Blackcap Updates and a package-only Configuration โ Platform โ Updates policy to System Admins. Automatic checking can surface Update Available without downloading anything, and automatic checking by itself never forces an update. The policy supports Manual-only checks or heartbeat-driven Automatic checks. With Automatic check selected, an additional opt-in can automatically apply an approved forward update when the Blackcap service restarts; Blackcap performs one fresh startup check, verifies/prepares the package, and hands activation to the existing independent updater. Automatic downgrade is prohibited. UI-driven Check โ Prepare โ Apply Update and Restart, live progress, Update History, and a locally retained Previous known-good release remain available. Source/unmanaged installations expose none of this update machinery. Source packages stay Source and Compiled packages stay Compiled through the workflow.
Source/unmanaged development installations expose a dedicated System โ Package Review panel immediately below the Blackcap version panel. Package Review is deliberately unavailable in packaged/immutable installations. A System Admin can manually compare the exact Python pins already declared in requirements.txt and requirements-cloud.txt with the latest stable PyPI releases compatible with the Python runtime performing the review. Blackcap also walks PyPI dependency metadata, including transitive dependency metadata within a bounded review graph, to calculate a Compatible Target for each exact pin. This prevents Select All from blindly pinning a dependency to a newer release that conflicts with another reviewed package (for example, a dependency whose parent package still requires an older major line). When the currently pinned version is itself incompatible with the reviewed dependency set, Package Review can surface a Dependency repair target that is lower than the current pin. Releases that cannot be dependency-verified or are blocked by unsatisfied constraints are excluded from Select All. Shared dependencies are presented once with Local + Cloud scope; local-only and cloud-only packages retain their narrower scope. Major-version changes are called out explicitly. Range-managed requirements are informational and are never rewritten automatically. The Package Review dialog keeps its title and Close action anchored while the package table scrolls, so maintenance actions remain accessible during long reviews.
Selecting an exact-pinned update changes only the requirement files in which that package is already declared, and writes the reviewed Compatible Target rather than blindly writing the absolute latest release. For example, updating OpenAI updates both requirements.txt and requirements-cloud.txt, while a Raspberry Pi/local-only dependency changes only requirements.txt. Select All selects every verified compatible update/repair currently shown. Update Selected Requirements edits the development working tree but intentionally does not run pip and does not perform any Git operation. Install Pending Packages is a separate explicit action that gathers the exact-pinned packages whose installed versions do not match the current runtime requirements and installs a bounded batch with direct targets such as python -m pip install --upgrade "openai==3.19.0". Intermediate bounded batches may temporarily be dependency-inconsistent, so pip check is deferred until the final requirements mismatch has been installed. The default batch maximum is eight direct packages and can be adjusted for a source environment with BLACKCAP_PACKAGE_REVIEW_MAX_INSTALL_PACKAGES (clamped to 1โ20). Recently changed requirement pins are installed first, and interrupted installs can be resumed because Blackcap recalculates remaining mismatches from the active environment. This keeps normal Package Review maintenance from asking pip to resolve the entire requirements file on resource-constrained hosts. When a bounded install updates Playwright itself, Package Review also runs the matching playwright install chromium post-install step so the Python package and managed Chromium revision remain synchronized.
Source/unmanaged systemd installations also expose Copy Full Reconcile Commands for deliberate full-environment maintenance. Blackcap builds the copied shell commands from the current environment: the active Python executable, application checkout, local-vs-cloud requirements file, detected primary Blackcap systemd service, and active companion application services. The command block stops the companion/application services to release memory, compares the current Python environment with every active top-level requirement, and installs only unsatisfied requirements as direct pip install --upgrade targets in bounded batches (four by default, configurable with BLACKCAP_PACKAGE_REVIEW_RECONCILE_BATCH_SIZE, clamped to 1โ20). It never hands the entire requirements graph to one pip install -r resolver transaction. After no mismatches remain, the helper verifies every active requirement again, synchronizes managed Chromium when Playwright is present, runs pip check, and restarts the detected services even when reconciliation returns an error. The copied command runs inside a subshell so a reconciliation failure does not log the administrator out of the host shell. Packaged/immutable installations do not expose Package Review or this command path. Blackcap never executes this stop/reconcile/restart sequence from the web request itself; the administrator copies it and runs it in a host shell.
Compiled packaged releases consume requirements-cloud.txt only at build time. The compiled build writes python-dependencies.json into the immutable release with the direct pins plus resolved runtime dependency versions. Packaged System diagnostics can display that provenance, but Package Review remains disabled and no target installation performs package upgrades in place.
The application uses a centralized database service, provider-aware repositories, organization scoping, idempotent migrations, and shared background-job infrastructure so the deployment paths remain behaviorally aligned. See Platform Stacks and Raspberry Pi Hardware, Packaged Distribution, and Application Updates.
๐พ Instance storage visibility
Normal authenticated instance reports include aggregate capacity for the filesystem containing Blackcap. Microwave Pie's software delivery and instance management service can therefore show total disk space, percentage used, and low-available-space fleet filters without inspecting file names or customer content. This telemetry follows the normal instance-report cadence and is advisory; it does not force cleanup or an application update.
More information
- Feature Catalog โ Browse every currently implemented product and technical capability.
- Configuration โ Understand platform, organization, and display-specific configuration scopes.
- Database Administration โ Inspect provider-aware data and maintenance tools.
- API Tester and Postman โ Test registered endpoints against the current instance.
- Performance and Job Status โ Review operational timing and background work.