Platform Stacks and Raspberry Pi Hardware
Audience: Deployment Administrator, Developer, Support
Related: Raspberry Pi Deployment · GCP Deployment · SQLite and PostgreSQL · Remote Pi Client Services
Blackcap shares one application architecture across Raspberry Pi and GCP, but the database, network front end, operating-system packages, Python dependency set, runtime paths, and local-hardware responsibilities differ. This document is the maintained platform-specific technology stack that replaced the undifferentiated stack in the historical root README.
Shared application stack
Both deployment paths use:
- Python 3 and Flask for Admin, Mobile, receiver, kiosk, API, authentication, configuration, and integration routes;
- Gunicorn for the production WSGI process;
- Jinja templates, JavaScript, and CSS for browser interfaces;
- a centralized database service with repositories, transactions, explicit-column queries, organization scoping, and idempotent migrations;
- Beautiful Soup and structured-data parsing for recipe extraction;
- Playwright Chromium for supported JavaScript-heavy capture and Menu rendering;
- Pillow, OpenCV, pytesseract, pyzbar, and PyMuPDF for image, OCR, QR, PDF, and render workflows;
- cryptography and OAuth libraries for protected secrets and provider connections;
- Dropbox and Google APIs for configured cloud integrations;
- OpenAI and Google GenAI SDKs for configured AI use cases;
- MaxMind-compatible local MMDB reading for optional GeoIP country lookup;
- database-backed background jobs, systemd services/timers, and managed cron schedules;
- the Blackcap Chrome Extension communicating through authenticated APIs.
Exact package versions are maintained in requirements.txt and requirements-cloud.txt. Do not copy package lists from this document into deployment automation.
Raspberry Pi server stack
The normal Pi application stack is:
Application checkout /home/pi/Blackcap-Pi
Python virtualenv /home/pi/inky_env
Primary service inky_admin.service
Gunicorn bind 127.0.0.1:8080 with local stunnel PROXY protocol
Default database SQLite
Default runtime data application-relative data directories
TLS front end stunnel (recommended Pi path)
Managed schedules /etc/cron.d/blackcap and selected systemd timers
Optional panel services blackcap-client.service and Let’s Cook watchers
Pi-specific Python/runtime packages include GPIO and SPI support such as gpiozero, lgpio, rpi-lgpio, RPi.GPIO, and spidev. The Waveshare e-paper driver is supplied through the project’s display integration/runtime environment rather than the cloud requirement set.
The Pi service runs database migrations before Gunicorn starts, normally with two workers and four threads. It may directly drive a Local E-Ink display, serve browser displays, act as a Remote Pi Client, or combine those roles.
GCP application stack
The supported GCP stack is:
Application host Google Compute Engine
Application checkout /opt/Blackcap
Python virtualenv /opt/blackcap_env
Primary service inky_admin.service
Gunicorn bind 127.0.0.1:8080 behind Nginx
Database Cloud SQL PostgreSQL
Database connection Cloud SQL Auth Proxy on localhost
TLS front end Nginx with HTTPS certificates
Runtime data /var/lib/blackcap
Environment file /etc/blackcap/blackcap.env
Managed schedules /etc/cron.d/blackcap and systemd services/timers
The cloud dependency set excludes Raspberry Pi GPIO/e-ink packages and adds psycopg and psycopg_pool for PostgreSQL. The deployment script installs PostgreSQL client tools, Nginx, Certbot, Playwright dependencies, and the Cloud SQL Auth Proxy binary.
The GCP service requires cloud-sql-proxy.service, runs provider-aware migrations before Gunicorn, and normally uses three workers with four threads. Nginx forwards trusted client-address information only from the local proxy boundary. The application host does not directly write a Pi panel; it prepares content for Hosted Web Receivers, Kiosks, Mock displays, and Remote Pi Clients.
SQLite and PostgreSQL differences
| Concern | Raspberry Pi / SQLite | GCP / PostgreSQL |
|---|---|---|
| Primary use | Low-overhead local/self-hosted database | Hosted multi-user Cloud SQL database |
| Connection | Local file through centralized DB service | Pooled network connection through Cloud SQL Auth Proxy |
| Concurrency | WAL mode and short transactions | PostgreSQL transactions and connection pooling |
| Types | SQLite affinity and text-compatible timestamps/JSON | Native booleans, timestamps, JSON/JSONB, sequences, and provider-aware introspection |
| Backup | Blackcap backup may include the SQLite database file | Cloud SQL backups are authoritative for the database; Blackcap platform backup excludes a live PostgreSQL database dump unless explicitly implemented |
| Maintenance | SQLite integrity, WAL, vacuum/checkpoint-oriented actions | PostgreSQL health, schema/parity, indexes, and Cloud SQL operations |
| SQL rules | Explicit projections and portable service/repository APIs | The same rules; provider-specific SQL stays behind adapters/helpers |
Both are current supported paths. PostgreSQL is not a future-only abstraction.
Raspberry Pi hardware baseline
Blackcap is designed to remain usable on modest Raspberry Pi hardware. The historical baseline is:
- Raspberry Pi Zero 2 W as the low-power optimization target;
- a 16 GB or larger microSD card, with more space recommended for recipe caches, backups, browser binaries, and logs;
- reliable network connectivity;
- an adequate power supply for the Pi and attached display hardware;
- optional headless configuration to reserve memory otherwise consumed by the desktop/GPU stack.
Faster Pi models are supported and improve Playwright, OCR, cache generation, and administrative responsiveness. Do not assume that every Pi has a panel attached.
Optimized e-ink hardware
The currently optimized physical display path is:
- Waveshare 13.3-inch e-Paper HAT (K);
- Good Display/Waveshare Type K four-gray controller behavior;
- resolution 960 × 680;
- Blackcap render profile
local-eink-gray4-960x680; - Waveshare driver family
epd13in3k; - SPI/GPIO connection from the Raspberry Pi;
- full-refresh-oriented delivery with controller-plane transport for structured four-gray content.
Blackcap’s visual rules and transport are tuned for this panel. Other displays can be represented through display profiles, but direct hardware support must not be assumed without a tested driver, waveform, dimensions, grayscale mapping, and locking path.
Why Pi and GCP remain one application
Blackcap intentionally uses one codebase for two primary operating models:
- Self-hosted Raspberry Pi households that want to run and own their own Blackcap installation, normally with SQLite and optionally an attached Local E-Ink display.
- Microwave Pie-hosted users who use the centrally operated GCP service, where Blackcap runs on Compute Engine with Cloud SQL PostgreSQL and can serve browser displays or Remote Pi Clients.
This design is about maintaining one product and one implementation, not about automatically sharing recipe or organization data between separate installations. A self-hosted Pi installation and the hosted GCP service have independent databases, files, users, organizations, credentials, and operational boundaries unless an explicit supported integration transfers data.
The shared codebase keeps the user-facing feature model consistent across both deployment choices and prevents fixes or new features from drifting into separate Pi-only and cloud-only applications. Platform-specific code should therefore remain limited to:
- database provider adapters and provider-specific migrations;
- deployment paths, packages, and service definitions;
- network/TLS front ends;
- filesystem and runtime locations;
- local hardware and e-ink services;
- host bootstrap values, defaults, and operational diagnostics.
Feature code should not fork into unrelated “Pi application” and “GCP application” implementations. Shared services, permissions, APIs, configuration definitions, and tests should remain provider-neutral wherever practical, with explicit platform adapters only where the operating environment genuinely differs.