# costagit33/kmkm architecture

> Architecture diagram of the GitHub repository costagit33/kmkm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/costagit33/kmkm
- Repository: https://github.com/costagit33/kmkm

## Overview

+1 KM is a mobile-first PWA and official Capacitor Android app for collecting location-verified NFC/QR stamps at real-world points. Participants open a tag, authenticate, stamp a published point, and earn character cards and gamification progress; routes, events, photos, and an admin console extend that journey. The graph separates client entry and experience, server domain services, media, and persistence. Several subsystem paths are supported by the README and source index, but their internal call paths were not sampled, so those links are omitted.

Main entry points: [`server/index.js`](https://github.com/costagit33/kmkm/blob/main/server/index.js) (Express API), [`server/midia/servico.js`](https://github.com/costagit33/kmkm/blob/main/server/midia/servico.js) (Media service), [`client/src/main.js`](https://github.com/costagit33/kmkm/blob/main/client/src/main.js) (App entry), [`server/admin.js`](https://github.com/costagit33/kmkm/blob/main/server/admin.js) (Admin services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Participant app"]
  node_app_entry["App entry<br/>[main.js]"]
  node_tag_flow["Tag stamping<br/>[tag.js]"]
  node_app_shell["App shell<br/>[app.js]"]
  node_api_client["API client<br/>[api.js]"]
  node_map["Map engines<br/>[map-engines.js]"]
  node_routes_view["Routes view<br/>[routes.js]"]
  node_gallery_client["Photo gallery<br/>[galeria.js]"]
  node_gamification_ui["Gamification UI"]
end

subgraph group_server["Server domain"]
  node_api_server["Express API<br/>[index.js]"]
  node_database[("MySQL database<br/>[database.js]")]
  node_creatures["Character cards<br/>[criaturas.js]"]
  node_events["Events and sponsors<br/>[eventos.js]"]
  node_gamification["Gamification rules<br/>[gamificacao.js]"]
  node_shared_rules["Shared XP rules<br/>[gamification.mjs]"]
  node_tag_security["Tag access keys<br/>[tag-acesso.js]"]
  node_n8n_events["Event webhook queue<br/>[eventos-n8n.js]"]
end

subgraph group_media["Point media"]
  node_media_routes["Media routes<br/>[rotas-publicas.js]"]
  node_media_service["Media service<br/>[servico.js]"]
  node_image_processing["Image processing<br/>[processar.js]"]
  node_media_storage["Media storage<br/>[armazenamento.js]"]
end

subgraph group_ops["Administration and operations"]
  node_admin_service["Admin services<br/>[admin.js]"]
end

node_participant(("Participant"))
node_n8n["n8n webhook"]

node_participant -->|"opens app or tag"| node_app_entry
node_app_entry -->|"opens tag"| node_tag_flow
node_app_entry -->|"loads app"| node_app_shell
node_app_entry -.->|"loads catalog"| node_api_client
node_app_shell -->|"requests account"| node_api_client
node_tag_flow -->|"submits stamp"| node_api_server
node_app_shell -->|"uses API"| node_api_server
node_api_server -->|"queries"| node_database
node_api_server -->|"checks event card"| node_events
node_api_server -.->|"validates tag key"| node_tag_security
node_api_server -.->|"resolves cards"| node_creatures
node_api_server -.->|"updates progress"| node_gamification
node_gamification -.->|"uses rules"| node_shared_rules
node_api_server -.->|"serves photos"| node_media_routes
node_media_routes -->|"loads approved photos"| node_media_service
node_media_service -->|"processes uploads"| node_image_processing
node_media_service -->|"reads and writes"| node_database
node_media_service -.->|"stores originals"| node_media_storage
node_api_server -.->|"routes admin"| node_admin_service
node_admin_service -->|"queries"| node_database
node_admin_service -->|"loads point covers"| node_media_service
node_admin_service -->|"checks windows"| node_events
node_api_server -.->|"records events"| node_n8n_events
node_n8n_events -->|"posts webhook"| node_n8n
node_api_client -->|"calls API"| node_api_server
node_map -->|"loads map config"| node_api_client
node_routes_view -->|"renders thumbnails"| node_gallery_client
node_gamification_ui -.->|"uses rules"| node_shared_rules

click node_app_entry "https://github.com/costagit33/kmkm/blob/main/client/src/main.js"
click node_tag_flow "https://github.com/costagit33/kmkm/blob/main/client/src/tag.js"
click node_app_shell "https://github.com/costagit33/kmkm/blob/main/client/src/app.js"
click node_api_client "https://github.com/costagit33/kmkm/blob/main/client/src/api.js"
click node_map "https://github.com/costagit33/kmkm/blob/main/client/src/map-engines.js"
click node_routes_view "https://github.com/costagit33/kmkm/blob/main/client/src/views/routes.js"
click node_gallery_client "https://github.com/costagit33/kmkm/blob/main/client/src/galeria.js"
click node_gamification_ui "https://github.com/costagit33/kmkm/blob/main/client/src/components/GamificationCards.jsx"
click node_api_server "https://github.com/costagit33/kmkm/blob/main/server/index.js"
click node_database "https://github.com/costagit33/kmkm/blob/main/server/db/database.js"
click node_admin_service "https://github.com/costagit33/kmkm/blob/main/server/admin.js"
click node_creatures "https://github.com/costagit33/kmkm/blob/main/server/criaturas.js"
click node_events "https://github.com/costagit33/kmkm/blob/main/server/eventos.js"
click node_gamification "https://github.com/costagit33/kmkm/blob/main/server/gamificacao.js"
click node_shared_rules "https://github.com/costagit33/kmkm/blob/main/shared/gamification.mjs"
click node_tag_security "https://github.com/costagit33/kmkm/blob/main/server/tag-acesso.js"
click node_media_routes "https://github.com/costagit33/kmkm/blob/main/server/midia/rotas-publicas.js"
click node_media_service "https://github.com/costagit33/kmkm/blob/main/server/midia/servico.js"
click node_image_processing "https://github.com/costagit33/kmkm/blob/main/server/midia/processar.js"
click node_media_storage "https://github.com/costagit33/kmkm/blob/main/server/midia/armazenamento.js"
click node_n8n_events "https://github.com/costagit33/kmkm/blob/main/server/integracoes/eventos-n8n.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_entry,node_tag_flow,node_app_shell,node_api_client,node_map,node_routes_view,node_gallery_client,node_gamification_ui toneBlue
class node_api_server,node_database,node_creatures,node_events,node_gamification,node_shared_rules,node_tag_security,node_n8n_events toneAmber
class node_media_routes,node_media_service,node_image_processing,node_media_storage,node_n8n toneMint
class node_admin_service toneRose
class node_participant toneIndigo
```

## Components

### Participant app

- [App entry](https://github.com/costagit33/kmkm/blob/main/client/src/main.js): `client/src/main.js`
- [Tag stamping](https://github.com/costagit33/kmkm/blob/main/client/src/tag.js): `client/src/tag.js`
- [App shell](https://github.com/costagit33/kmkm/blob/main/client/src/app.js): `client/src/app.js`
- [API client](https://github.com/costagit33/kmkm/blob/main/client/src/api.js): `client/src/api.js`
- [Map engines](https://github.com/costagit33/kmkm/blob/main/client/src/map-engines.js): `client/src/map-engines.js`
- [Routes view](https://github.com/costagit33/kmkm/blob/main/client/src/views/routes.js): `client/src/views/routes.js`
- [Photo gallery](https://github.com/costagit33/kmkm/blob/main/client/src/galeria.js): `client/src/galeria.js`
- [Gamification UI](https://github.com/costagit33/kmkm/blob/main/client/src/components/GamificationCards.jsx): `client/src/components/GamificationCards.jsx`

### Server domain

- [Express API](https://github.com/costagit33/kmkm/blob/main/server/index.js): `server/index.js`
- [MySQL database](https://github.com/costagit33/kmkm/blob/main/server/db/database.js): `server/db/database.js`
- [Character cards](https://github.com/costagit33/kmkm/blob/main/server/criaturas.js): `server/criaturas.js`
- [Events and sponsors](https://github.com/costagit33/kmkm/blob/main/server/eventos.js): `server/eventos.js`
- [Gamification rules](https://github.com/costagit33/kmkm/blob/main/server/gamificacao.js): `server/gamificacao.js`
- [Shared XP rules](https://github.com/costagit33/kmkm/blob/main/shared/gamification.mjs): `shared/gamification.mjs`
- [Tag access keys](https://github.com/costagit33/kmkm/blob/main/server/tag-acesso.js): `server/tag-acesso.js`
- [Event webhook queue](https://github.com/costagit33/kmkm/blob/main/server/integracoes/eventos-n8n.js): `server/integracoes/eventos-n8n.js`

### Point media

- [Media routes](https://github.com/costagit33/kmkm/blob/main/server/midia/rotas-publicas.js): `server/midia/rotas-publicas.js`
- [Media service](https://github.com/costagit33/kmkm/blob/main/server/midia/servico.js): `server/midia/servico.js`
- [Image processing](https://github.com/costagit33/kmkm/blob/main/server/midia/processar.js): `server/midia/processar.js`
- [Media storage](https://github.com/costagit33/kmkm/blob/main/server/midia/armazenamento.js): `server/midia/armazenamento.js`

### Administration and operations

- [Admin services](https://github.com/costagit33/kmkm/blob/main/server/admin.js): `server/admin.js`

### Other components

- **Participant**
- **n8n webhook**

## Connections

- Participant → App entry: opens app or tag (evidence: `README.md`)
- App entry → Tag stamping: opens tag (evidence: `client/src/main.js`)
- App entry → App shell: loads app (evidence: `client/src/main.js`)
- App entry → API client: loads catalog
- App shell → API client: requests account (evidence: `client/src/app.js`)
- Tag stamping → Express API: submits stamp (evidence: `README.md`)
- App shell → Express API: uses API (evidence: `README.md`)
- Express API → MySQL database: queries (evidence: `server/index.js`)
- Express API → Events and sponsors: checks event card (evidence: `server/index.js`)
- Express API → Tag access keys: validates tag key (evidence: `server/index.js`)
- Express API → Character cards: resolves cards (evidence: `server/index.js`)
- Express API → Gamification rules: updates progress (evidence: `server/index.js`)
- Gamification rules → Shared XP rules: uses rules (evidence: `server/gamificacao.js`)
- Express API → Media routes: serves photos (evidence: `server/index.js`)
- Media routes → Media service: loads approved photos (evidence: `server/midia/rotas-publicas.js`)
- Media service → Image processing: processes uploads (evidence: `server/midia/servico.js`)
- Media service → MySQL database: reads and writes (evidence: `server/midia/servico.js`)
- Media service → Media storage: stores originals
- Express API → Admin services: routes admin (evidence: `server/index.js`)
- Admin services → MySQL database: queries (evidence: `server/admin.js`)
- Admin services → Media service: loads point covers (evidence: `server/admin.js`)
- Admin services → Events and sponsors: checks windows (evidence: `server/admin.js`)
- Express API → Event webhook queue: records events (evidence: `server/index.js`)
- Event webhook queue → n8n webhook: posts webhook (evidence: `server/integracoes/eventos-n8n.js`)
- API client → Express API: calls API (evidence: `README.md`)
- Map engines → API client: loads map config (evidence: `client/src/map-engines.js`)
- Routes view → Photo gallery: renders thumbnails (evidence: `client/src/views/routes.js`)
- Gamification UI → Shared XP rules: uses rules (evidence: `client/src/components/GamificationCards.jsx`)
