Technical documentation#
This is the technical part of the Fyndi guide: how the Android app, the API, the website and the server fit together, where the data lives, how releases are built and how work on the project is organised.
What is in this section#
These pages describe the machinery behind the app, not the screens you tap. Each one answers a single question and points to the places where the answer is checkable in code.
| Page | Question it answers |
|---|---|
| Architecture | What is Fyndi made of, and what talks to what? |
| Data model | Which object lives in the database, and which is just a file? |
| Staff panel | What can staff do, and where? |
| Quality and checks | How do we know something is not broken — before and after release? |
| APK releases | Where does the app come from, and how is it signed? |
| Change history | What changed in which release, in plain language? |
| Map and markers | How are markers drawn, and what do they cost per frame? |
| 3D character | How is the blocky character built? |
| Workflow | Where does work live and who closes it? |
How to read the technical pages#
Read them in any order — every page starts from a one-sentence answer and only then goes into numbers. A suggested route depending on what you need:
- You want to know what the product is made of — start with Architecture and then Data model.
- You want to check a claim (“is that measurement real?”) — Quality and checks lists the gates, the commands and the numbers they produced.
- You want to change the content (a route, a stop, a find) — Staff panel and then Workflow.
- You want the app on your phone — APK releases, and for the player-facing steps Installation.
Two conventions are worth knowing before you start:
- Paths and command names are written as they are in the repository. Where something is a secret, the guide says what it is and where it lives instead of repeating its value — that is deliberate, not an omission.
- The app and the API have separate version numbers. The app version (the one you install) and the API version (the server) move independently, so a page can mention both.
List of technical pages#
Vocabulary used across the technical pages#
| Term | Meaning in this guide |
|---|---|
| map | the screen you start from — pawn, routes, finds, bots |
| find | a side collectible, always visible on the map, never a route stop |
| route | an ordered list of stops to visit in sequence |
| stop | a single place on a route with a completion rule (GPS, puzzle, AR) |
| exploring | walking routes and completing stops |
| bot | an NPC character controlled by the server |
| offline pack | a versioned set of city content to download to the phone |
| character | the 3D (blocky) figure, in the app, on the website and in the panel |
| gate, check | an automated test that can stop a change |
| release | one published APK, with a tag and a version code |
| release key | the private key stored on the server that signs the APK |
| project brain | the project's knowledge directory in the repository, browsable in the panel |
Quick index of the technical pages#
| Page | Main sections |
|---|---|
| Architecture | parts, data flow, client layers, rationale |
| Data model | what lives where, hashed answers, files and models |
| Staff panel | what it is, roles, pages, content creator |
| Quality and checks | gates, running them, the docs gate, on a device |
| APK releases | download, build, signing, numbering |
| Change history | how to read it, latest, earlier, full history |
| Map and markers | one layer, types and colours, one source of icons, performance |
| 3D character | three layers, paint or block, dimensions, animations, wardrobe |
| Workflow | planner and issues, columns, the agent, docs and the brain |
Documented for app version 0.120.1 (updated 2026-09-26).
Machine translation — the Polish version prevails.