Blackcap documentation is organized by user task, feature, deployment target, and stable operational responsibility. Start with the section that matches the work you are doing.

🧭 Start Here

Blackcap Overview — Blackcap is a recipe, meal-planning, shopping, kitchen-display, and guided-cooking application.
Feature Catalog — Maintained, categorized coverage of every current major product, administration, integration, and deployment capability.
Installation — Use the repository deployment scripts for a new installation.
First Run — Confirm that database migrations complete, inky_admin.service is healthy, and the configured external URL matches the address users will open.

🚀 Deploy Blackcap

Platform Stacks and Raspberry Pi Hardware — Compares the Pi/SQLite and GCP/PostgreSQL stacks and documents the Raspberry Pi and Waveshare hardware baseline.
Raspberry Pi Deployment — A Raspberry Pi can run the Blackcap server, directly drive one local e-ink panel, act as a Remote Pi Client, or combine server and local-client responsibilities.
Raspberry Pi Client Services — Explains the attached client, polling, panel ownership, Let’s Cook watchers, managed schedules, service-role matrix, and GCP server support for Remote Pi Clients.
GCP Deployment — The supported GCP path uses a Compute Engine application host, Cloud SQL PostgreSQL, Cloud SQL Auth Proxy on localhost, Gunicorn, Nginx, HTTPS certificates, systemd-managed services, and /etc/cron.d/blackcap for managed schedules.
Application Updates — For an ordinary Blackcap application change, deploy or copy the changed files into the installed checkout, run idempotent migrations when the service pre-start step does not already do so, restart inky_admin.service, and validate the affected feature.
Environment Variables and Secrets — Store deployment-specific secrets and environment overrides in /etc/blackcap/blackcap.env or another root-protected environment file referenced by systemd.
Reverse Proxy and TLS — Raspberry Pi and GCP deployments use different front ends.
Background Jobs and Schedules — Blackcap uses database-backed background jobs for user-initiated and system work, systemd services for persistent watchers, systemd timers for selected maintenance tasks, and /etc/cron.d/blackcap for managed recurring commands.

🛠️ Administer Blackcap

Organizations — Organizations are the primary tenant boundary in Blackcap.
Users, Permissions, and Authentication — Blackcap supports internal/password authentication, invitations, password reset, TOTP MFA, recovery codes, trusted-browser tokens, API Tokens, and configured external login providers.
Configuration — Blackcap configuration is split between bootstrap INI/environment settings and database-backed scoped settings.
Backups and Restore — Blackcap supports local backups and configured Dropbox or Google Drive destinations.
Database Administration — Database Admin provides provider-aware inspection, maintenance, schema export, saved queries, SQL Console safeguards, data-problem review, resource relationships, restore actions, and parity diagnostics.
Regression Testing — Blackcap includes an administrative regression harness for immediate, scheduled, resumable, and diagnostic-clone runs.
Performance and Job Status — Performance presents operational trends, duration and queue metrics, resource snapshots, display/render activity, email and backup timing, slow requests, and regression comparisons.
Audit, Access Activity, and Logging — Blackcap records authentication, configuration, recipe, meal-planning, shopping, backup, display, AI, and administrative activity according to the feature and retention policy.
GeoIP and Access Location — Explains why Blackcap tracks country-level access, how proxy-aware IP resolution works, and where login, display, API, voice, support, and activity surfaces use it.
Data Retention and Purge — Purge behavior is domain-aware rather than a generic table delete.
Support Requests — Authenticated Admin and Mobile users can submit a Support Request when platform support is configured.
API Tester and Postman — API Tester exposes registered Blackcap endpoints with role-aware execution, sanitized examples, option resolution, authentication context, and Postman export.
Instance Reporting — Privacy-conscious instance reporting provides deployment identity, lifecycle, version, and safe operational metadata for configured reporting workflows.

🍽️ Use Recipes

Recipes and the Recipe Library — The Recipe Library stores organization-scoped recipes captured from normal web pages, social sources, photos or screenshots, manual entry, shared recipes, and supported import formats.
Recipe Import and Discovery — Normal recipe import accepts supported URLs and extracts structured data using deterministic sources first, including JSON-LD and page content, with rendering or slower-site handling when required.
Recipe Editing and Cache Artifacts — Recipe content can be edited from Admin and Mobile.
Recipe Sharing — Blackcap supports email-ready PDF sharing and Blackcap-to-Blackcap share links.
Social Recipe Import — Social Recipe Import supports URL submission and extension-assisted capture for YouTube, TikTok, Instagram, Pinterest, and recognized related URL forms.
AI Recipe Image Generation — Blackcap can generate recipe images through configured AI providers and quality profiles.

📅 Plan Meals

Meal Planner — Meal Planner supports organization-scoped week and month planning, configurable week start, meal slots, optional slot times, multiple recipes or manual items in a slot, recipe multipliers, moves, review, PDF/email output, shopping-list generation, and Day/Week/Month display rendering.

🛒 Use Shopping Lists

Shopping Lists and Shop a List — Shopping Lists can be created from recipes, selected meal-plan scope, Household List or external sources, and manual items.
External and Household Shopping — Blackcap can merge supported household/external shopping sources into the shopping workflow and can hand off lists through configured Shop With providers.
Chrome Extension Shop With — Covers Shop a List, provider/store selection, attended browser automation, item completion, Household List check-off, failure recovery, and diagnostics.

🧺 Manage Kitchen Inventory

Kitchen Inventory — Kitchen Inventory tracks organization-scoped household items by canonical identity, grocery department, storage location, and Have It state.

🖥️ Use Displays

Displays and Connections — Blackcap display types include Local E-Ink, Hosted Web Receiver, Kiosk, Remote Pi Client, and Mock displays.
Assigning and Scheduling Display Content — Assign Content supports immediate and scheduled display content, including Menu, Recipe, meal-plan views, Today & Tomorrow, Let’s Cook, Return to Default, and supported client behavior.
Remote Pi Client — Remote Pi Client mode links a Raspberry Pi display client to a Blackcap server.
E-Ink Rendering — The supported Waveshare 13.3-inch K path is 960×680 with four grayscale levels.
Menu Refresh and Rendering — Menu mode renders an organization’s configured menu source for supported displays.
Noun Project Footer Images — Covers rule matching, placement, caching, credentials, licensing, and display rendering for ingredient/category images in menu and meal-plan footers.

🧑‍🍳 Cook with Let’s Cook

Let’s Cook — Let’s Cook is Blackcap’s guided-cooking mode.
Let’s Cook Controls and Timers — Interactive controls support previous/next step, tapping the current step to advance where enabled, ingredient or preparation completion, timer start/pause/resume/stop/cancel, and bounded minute adjustments.

🤖 Use and Administer AI

AI in Blackcap — Blackcap’s AI subsystem separates providers, provider connections, use cases, quality/intelligence profiles, prompts, usage reservations, AI Seeds, monthly allotments, reporting, and generated-asset retention.
AI Providers and Connections — AI provider adapters expose declared capabilities through a shared registry and base interface.
AI Seeds and Usage — AI Seeds are Blackcap’s product currency for AI use.

🧩 Use the Chrome Extension

Blackcap Chrome Extension — The Chrome Extension connects a signed-in user to Blackcap using a user-owned API Token.
Chrome Extension Recipe Capture — Capture Page collects available structured recipe data, page metadata, visible content, and supported social evidence, then lets the user review or complete the recipe before submission.
Chrome Extension Shop With — Covers Shop a List, provider/store selection, attended browser automation, item completion, Household List check-off, failure recovery, and diagnostics.
Chrome Extension Release and Privacy — Release documentation covers local loading, versioning, packaging, Chrome Web Store listing content, privacy disclosures, permission justification, screenshots, and review checks.

🎮 Play Games

Games and Trivia — Blackcap includes organization-aware trivia games such as berry trivia and cooking-terms trivia.

🔌 Integrations

Email Integration — Blackcap sends branded HTML email with plain-text alternatives through configured SMTP.
Cloud Storage Integrations — Dropbox and Google Drive connections provide optional backup destinations.
Voice Assistants — Blackcap supports Alexa Custom Skill, Alexa Smart Home, and Google Home integrations for supported Let’s Cook, display, timer, and household shopping actions.
Shop With Integrations — Shop With integrations hand a Blackcap shopping workflow to a configured external provider or assisted browser flow.
Authentication Providers — Blackcap has a provider registry for configured external login providers, including Google, Apple, LinkedIn, Facebook, X, GitHub, Microsoft, and Amazon where implemented.

⚙️ Develop Blackcap

Application Architecture — Blackcap is a modular Flask application served by Gunicorn.
Database Service and Data Access — All application database work should use the centralized database service, repositories, transactions, and provider adapters.
SQLite and PostgreSQL — SQLite is the default Raspberry Pi database and uses WAL mode and application-controlled migrations.
Database Migrations — Blackcap migrations are ordered, idempotent, provider-aware, and executed before Gunicorn workers start.
Background Job Architecture — Background work is represented in the database with organization and requesting-user context, queue/family metadata, status, progress, heartbeat, result, and failure details.
Testing — Use focused unit and contract tests for services, routes, provider adapters, rendering, and documentation structure, then use the Blackcap regression harness for end-to-end verification.
API Architecture — Blackcap APIs are organized by feature blueprints and registered in the API Tester registry.
Security and Organization Scoping — Security is enforced through authentication, account status, role permissions, Active Organization context, resource ownership, CSRF protection, rate limiting, safe external fetch rules, secret handling, provider request validation, and audit logging.
UI, Icons, and Documentation Assets — Shared UI symbols, field-specific emoji controls, country flags, Noun Project assets, recipe thumbnails, e-ink images, and documentation previews should use descriptive filenames, accessible labels, and the established asset services.
Blackcap-Safe Emoji — Explains why Blackcap uses a curated emoji registry, how pickers and generated assets work, and how UI/content emoji remain portable across browsers, PDFs, and e-ink rendering.
Documentation Standards — Blackcap documentation is organized by feature, subsystem, user task, deployment target, or stable operational responsibility.
Terminology — Use the current product terms consistently: Blackcap, Blackcap Admin, Blackcap Pi Admin, Microwave Pie, AI Seeds, API Tokens, Let’s Cook, Recipe Library, Meal Planner, Shopping Lists, Kitchen Inventory, Hosted Web Receiver, Kiosk, Remote Pi Client, Local E-Ink, System Admin, Org Admin, Active Organization, Default Organization, SQLite, PostgreSQL, GCP, and Raspberry Pi.

⚠️ Troubleshoot Blackcap

Troubleshooting — Start with the feature-specific page, then check Job Status, Performance, logs, database health, and deployment services.
Deployment Troubleshooting — Check the target deployment guide, systemd unit status, journal logs, environment file permissions, migration pre-start output, reverse-proxy/TLS health, cron installation, and target-specific paths.
Display Troubleshooting — Confirm display type, Active Organization, assigned/default content, receiver or client connection, preview generation, physical acknowledgement, watcher configuration, and render profile.
Recipe Import Troubleshooting — Confirm the normalized source URL, deterministic evidence found, slow-site policy, extension capture evidence, completeness status, AI enhancement decision, thumbnail source, and cache build result.
AI Troubleshooting — Check provider connection state, use-case capability, model/profile configuration, Seed balance and reservation state, provider error details, validation failures, and asset retention.
Backup Troubleshooting — Check the selected provider, connection state, organization scope, local and restore-staging paths, job details, retention, and database-provider boundary.
Database Troubleshooting — Run the provider-aware health and parity tools, inspect migration status, verify the configured backend and connection, review Database Admin data problems, and check for organization-scope or SQL portability issues.
Diagnostic Clones — Creates an isolated organization copy for reproducing configuration, recipe, planner, shopping, display, inventory, Let’s Cook, or current AI-state issues without modifying the source organization.
Create a Support Request — Use the Blackcap account menu to send a case-numbered request with safe page, deployment, build, schema, runtime, browser, image, IP/GeoIP, and audit context when platform support is configured.

On this page