How costagit33/kmkm works
+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: index.js Express API · servico.js Media service · main.js App entry · admin.js Admin services
Components 23
Participant app
- App entry
client/src/main.js - Tag stamping
client/src/tag.js - App shell
client/src/app.js - API client
client/src/api.js - Map engines
client/src/map-engines.js - Routes view
client/src/views/routes.js - Photo gallery
client/src/galeria.js - Gamification UI
client/src/components/GamificationCards.jsx
Server domain
- Express API
server/index.js - MySQL database
server/db/database.js - Character cards
server/criaturas.js - Events and sponsors
server/eventos.js - Gamification rules
server/gamificacao.js - Shared XP rules
shared/gamification.mjs - Tag access keys
server/tag-acesso.js - Event webhook queue
server/integracoes/eventos-n8n.js
Point media
- Media routes
server/midia/rotas-publicas.js - Media service
server/midia/servico.js - Image processing
server/midia/processar.js - Media storage
server/midia/armazenamento.js
Administration and operations
- Admin services
server/admin.js
Other components
- Participant
- n8n webhook
Connections 28
- Participant → App entry: opens app or tag
README.md - App entry → Tag stamping: opens tag
client/src/main.js - App entry → App shell: loads app
client/src/main.js - App entry → API client: loads catalog
- App shell → API client: requests account
client/src/app.js - Tag stamping → Express API: submits stamp
README.md - App shell → Express API: uses API
README.md - Express API → MySQL database: queries
server/index.js - Express API → Events and sponsors: checks event card
server/index.js - Express API → Tag access keys: validates tag key
server/index.js - Express API → Character cards: resolves cards
server/index.js - Express API → Gamification rules: updates progress
server/index.js - Gamification rules → Shared XP rules: uses rules
server/gamificacao.js - Express API → Media routes: serves photos
server/index.js - Media routes → Media service: loads approved photos
server/midia/rotas-publicas.js - Media service → Image processing: processes uploads
server/midia/servico.js - Media service → MySQL database: reads and writes
server/midia/servico.js - Media service → Media storage: stores originals
- Express API → Admin services: routes admin
server/index.js - Admin services → MySQL database: queries
server/admin.js - Admin services → Media service: loads point covers
server/admin.js - Admin services → Events and sponsors: checks windows
server/admin.js - Express API → Event webhook queue: records events
server/index.js - Event webhook queue → n8n webhook: posts webhook
server/integracoes/eventos-n8n.js - API client → Express API: calls API
README.md - Map engines → API client: loads map config
client/src/map-engines.js - Routes view → Photo gallery: renders thumbnails
client/src/views/routes.js - Gamification UI → Shared XP rules: uses rules
client/src/components/GamificationCards.jsx