Architecture Overview

How it all fits together; each component then has its own deep-dive page.

Components and how they talk

   ┌───────────────┐         ┌────────────────┐        ┌──────────────────┐
   │  Mobile app    │        │   Web app      │        │   Admin panel    │
   │  (Flutter)     │        │  (Nuxt SPA)    │        │  (Vue SPA)       │
   │ org.bmekonza   │        │ [domain TBD]   │        │ admin.bme-konza  │
   └──────┬─────────┘        └──────┬─────────┘        └────────┬─────────┘
          │  HTTPS/JSON             │  HTTPS/JSON               │ HTTPS/JSON
          │                         │                           │
          └───────────────┬─────────┴───────────────┬───────────┘
                          ▼                         │
               ┌────────────────────┐               │
               │   API (Go/Fiber)   │               │
               │  api.bme-konza.org │               │
               │   /api/v1, /api/v2 │               │
               └───┬───────┬────────┘               │
                   │       │                        │
            ┌──────▼──┐ ┌──▼──────────────┐   ┌─────▼──────────────────┐
            │Postgres │ │ Firebase        │   │ Firebase (client SDK)  │
            │(Coolify)│ │  Admin SDK:     │   │  Auth, Storage, FCM,   │
            └─────────┘ │  - Auth         │   │  Analytics, Crashlytics│
                        │  - Cloud Storage│   └────────────────────────┘
                        │  - FCM push     │
                        └─────────────────┘

Clients (app, web, admin) authenticate users with Firebase Auth, then call the Go API over HTTPS for all domain data.
Two more surfaces sit outside this request path: the static marketing/legal site (bme-konza.org, see 09-website.md) and the developer-docs site (hq.bme-konza.org, MkDocs, see 18-dev-docs-hq.md).
⚠️ The Nuxt web app's public domain is currently unconfirmed (it is not hq., which is the dev-docs site) — see 08-web-platform.md.
The API owns the relational data in Postgres and uses the Firebase Admin SDK for push notifications (FCM), and to delete files from Firebase Cloud Storage.
File uploads (resource PDFs, response/question images, profile photos) go to Firebase Cloud Storage; the API stores the resulting URLs/paths in Postgres. See 12-file-storage.md.
The marketing site is static and also hosts the legal pages and the Android assetlinks.json for deep linking.

Core domain (what the platform does)

A knowledge base + Q&A + document exchange for biomedical equipment:

Equipment → Brands → Models taxonomy; Resources (manuals, videos, webinars) are linked to models via resource_references.
Questions & Responses (Q&A), with upvotes, tags, anonymous posting, and acceptance.
Reputation/points & tiers/leaderboard — users earn points (configurable per action) and are ranked into tiers.
Requests — users request manuals/resources that don't exist yet.
Notifications (in-app + FCM push), announcements, banners, feedback, find-an-expert / social link-up, and analytics/reporting.
Full-text & trigram search over resources and questions (Postgres tsvector + pg_trgm).

See 06-database.md for the data model and 05-api-backend.md for the API surface that exposes all of this.

API versions

The API exposes both /api/v1 (legacy) and /api/v2 (current) route groups. v2 uses Firebase Auth with role-based authorization and adds banners, reports, and a moderation admin/ group. The system is mid-migration from v1 to v2; new work should target v2. See api-backend.md. [TODO: which clients still call v1.]

Background processing

The API runs background workers (monthly reports, reputation-point processing, Q&A reminders, question notifications, search logging, user-interaction reports). See 05-api-backend.md and 13-monitoring-logging.md.