GreyScreen, documented
GreyScreen TV is a streaming platform for African film and series: a public website, a phone app with an embedded webview, an Android TV app, an admin back office, two REST APIs, an on-demand video encoder and an HLS streaming server.
This room is the engineering view of that system. It is written to answer three questions quickly:
- What runs? Which repositories, services, buckets and databases make up the platform.
- How do I run it? From a clean machine to a working local stack, against the test environment.
- How does a change ship? Which branch, which pipeline, which order, and how to undo it.
Start with the shape
The platform in one picture
Every public request enters through the gateway; every private one stays inside.
The same system, laid out automatically. Use the controls to zoom, open it full screen, or download it for a deck.
Use the interactive architecture for the full map, or read How GreyScreen works for the plain-language version.
How to read this room
| Section | Use it when |
|---|---|
| Start here | You are new to the product and need the mental model, the map, and the vocabulary. |
| Setup | You need to run one repository locally, or all of them, without copying a production secret. |
| Architecture | You are changing a flow and need the contracts between services. |
| Operations | You are deploying, rolling back, or diagnosing a live incident. |
| Reference | You need the environment variable names, the endpoint list, or the branch rules. |
Ground rules
Service-account keys, .env.*.local files, signing certificates and orchestrator keys are
named here only by path, never by value. Do not paste a secret into an example, a screenshot
or a diagram. If you need a value, fetch it from the secret store or ask the maintainer.
Several READMEs, and the old ARCHITECTURE/ visualisation, still describe MongoDB, Redis,
TUS or n8n. When prose and code disagree, trust the code and the repository paths linked from
these pages. The source-of-truth index is the
short list of files that actually ship.
Application repositories develop on test; main is the release line. Do not merge test
into main wholesale — the website selects its Firebase identity by branch, so that merge
would silently point production at the test project. Release by cherry-pick. See
Branch strategy.
Scope and freshness
This documentation covers the repositories under
/shared/from_machine_c/PROJECTS/GREYSCREEN/DEV_PROCESS, plus the reverse proxy under
PROJECTS/REVERSE_PROXY_SERVERS/vps-reverse-proxy. The architecture was last reviewed
against the code on 2026-10-24. Re-verify operational details before acting on them.
The diagrams are generated from data in this repository (src/data/architecture), not from a
screenshot. When a service, port or contract changes, update the data file and the diagrams
follow.