# renidantass/mapinhaa architecture

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

- Interactive diagram: https://gitdiagram.com/renidantass/mapinhaa
- Repository: https://github.com/renidantass/mapinhaa

## Overview

1. **Arquitetura geral**
   - É um jogo 100% front-end, executado diretamente em `index.html` no navegador.
   - A aplicação é organizada como uma SPA simples em JavaScript modular, com separação clara entre **estado**, **lógica**, **eventos** e **UI**.

2. **Camada de apresentação**
   - `index.html` define a estrutura principal do jogo.
   - `style.css` contém toda a estilização visual, incluindo o visual moderno “glassmorphism” e a adaptação responsiva.
   - A pasta `images/` fornece ícones, favicons e elementos visuais auxiliares do jogo.

3. **Estado central do jogo**
   - `js/state.js` representa o estado compartilhado da aplicação.
   - Esse estado deve concentrar informações como rodada atual, pontuação, cidade alvo, coordenadas, chave da API, e flags de fluxo do jogo.
   - É o ponto de referência para a lógica e para a UI, evitando espalhar dados pela aplicação.

4. **Referências de DOM e objetos de integração**
   - `js/elements.js` centraliza os elementos do DOM usados pelo jogo e possivelmente instâncias/handles relacionados ao mapa.
   - Isso cria uma camada de acesso única para a UI e para os listeners, reduzindo acoplamento com seletores espalhados pelo código.

5. **Lógica de jogo**
   - `js/logic.js` concentra as regras do BairroGuessr e não deve manipular interface diretamente.
   - Aqui ficam as operações centrais: iniciar partida, gerar localizações, calcular pontuação, validar respostas, lidar com geocodificação e integrar chamadas externas.
   - É o núcleo funcional da aplicação.

6. **Camada de UI**
   - `js/ui.js` é responsável apenas por alterar a interface: mostrar telas, atualizar textos, feedback visual, resultados e estados de jogo.
   - A intenção explícita do repositório é manter a UI isolada da lógica, para que mudanças visuais não afetem as regras do jogo.

7. **Eventos e fluxo de interação**
   - `js/listeners.js` faz a ponte entre o usuário e o restante da aplicação.
   - Ele registra event listeners dos controles e traduz ações como “iniciar jogo”, “usar minha localização”, “enviar palpite” ou “avançar rodada” em chamadas para `logic.js` e `ui.js`.
   - Esse arquivo funciona como camada de orquestração de eventos.

8. **Fluxo principal de dados**
   - O usuário informa coordenadas iniciais ou usa geolocalização.
   - A aplicação usa essas informações para restringir a cidade e gerar locais dentro dela.
   - O jogo então apresenta o desafio, coleta o palpite do jogador, calcula a distância/precisão e atualiza a pontuação e a interface.

9. **Dependências externas que moldam a arquitetura**
   - O projeto depende da **Google Maps API** com permissões para:
     - Maps JavaScript API
     - Street View Static API
     - Geocoding API
     - Geolocation API
   - Isso significa que a experiência do jogo depende de serviços externos para mapa, busca de endereço/cidade, localização e imagens de Street View.

10. **Recursos de localização automática e restrição de cidade**
   - Há duas extensões funcionais importantes: detecção da localização atual do usuário e tentativa de limitar a geração de desafios à cidade detectada.
   - Essas funcionalidades criam um fluxo adicional: localização/geocoding → identificação da cidade → geração de desafios dentro do limite geográfico.

11. **Efeitos visuais e canvas**
   - O README indica uso de **HTML5 Canvas** para efeitos visuais.
   - Isso sugere uma camada estética complementar à UI DOM, provavelmente para enriquecer a experiência sem alterar as regras do jogo.

12. **Como desenhar o diagrama**
   - No centro, coloque `state.js` como fonte de verdade.
   - Ao redor, conecte `listeners.js` como entrada de eventos, `logic.js` como motor de regras, `ui.js` como saída visual, e `elements.js` como acesso compartilhado ao DOM/objetos.
   - Fora do app, represente a dependência de Google Maps/Geocoding/Geolocation e a camada estática de assets (`style.css`, `images/`, `index.html`).

Main entry points: [`js/logic.js`](https://github.com/renidantass/mapinhaa/blob/main/js/logic.js) (logic.js), [`js/ui.js`](https://github.com/renidantass/mapinhaa/blob/main/js/ui.js) (ui.js), [`js/state.js`](https://github.com/renidantass/mapinhaa/blob/main/js/state.js) (state.js), [`js/listeners.js`](https://github.com/renidantass/mapinhaa/blob/main/js/listeners.js) (listeners.js)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App shell"]
  node_index["index.html<br/>entry page<br/>[index.html]"]
  node_style["style.css<br/>styles<br/>[style.css]"]
  node_images["images<br/>assets"]
end

subgraph group_core["Game core"]
  node_state[("state.js<br/>shared state<br/>[state.js]")]
  node_elements["elements.js<br/>dom handles<br/>[elements.js]"]
  node_listeners["listeners.js<br/>events<br/>[listeners.js]"]
  node_logic["logic.js<br/>rules engine<br/>[logic.js]"]
  node_ui["ui.js<br/>presentation<br/>[ui.js]"]
end

subgraph group_external["External services"]
  node_maps["Google Maps API<br/>maps platform"]
  node_geoloc(("Browser geolocation<br/>browser API"))
  node_canvas(("Canvas effects<br/>visual layer"))
end

node_listeners -->|"start / guess / next"| node_logic
node_listeners -->|"feedback"| node_ui
node_logic -->|"read / write"| node_state
node_ui -->|"render from"| node_state
node_ui -->|"update dom"| node_elements
node_listeners -->|"bind controls"| node_elements
node_elements -->|"find nodes"| node_index
node_ui -->|"styled by"| node_style
node_ui -->|"icons / art"| node_images
node_logic -->|"geocode / street view"| node_maps
node_logic -->|"current location"| node_geoloc
node_logic -->|"effects"| node_canvas
node_state -.->|"drives flow"| node_logic
node_state -.->|"drives view"| node_ui

click node_index "https://github.com/renidantass/mapinhaa/blob/main/index.html"
click node_style "https://github.com/renidantass/mapinhaa/blob/main/style.css"
click node_images "https://github.com/renidantass/mapinhaa/tree/main/images"
click node_state "https://github.com/renidantass/mapinhaa/blob/main/js/state.js"
click node_elements "https://github.com/renidantass/mapinhaa/blob/main/js/elements.js"
click node_listeners "https://github.com/renidantass/mapinhaa/blob/main/js/listeners.js"
click node_logic "https://github.com/renidantass/mapinhaa/blob/main/js/logic.js"
click node_ui "https://github.com/renidantass/mapinhaa/blob/main/js/ui.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_index,node_style,node_images toneBlue
class node_state,node_elements,node_listeners,node_logic,node_ui toneAmber
class node_maps,node_geoloc,node_canvas toneMint
```

## Components

### App shell

Static page, styling, shared DOM handles, and visual assets.

- [index.html](https://github.com/renidantass/mapinhaa/blob/main/index.html): entry page · Single-page entry point that hosts the game UI. · `index.html`
- [style.css](https://github.com/renidantass/mapinhaa/blob/main/style.css): styles · Global styling and responsive glassmorphism presentation. · `style.css`
- [images](https://github.com/renidantass/mapinhaa/tree/main/images): assets · Icons, favicons, and other visual assets. · `images`

### Game core

Shared state, orchestration, rules, and UI updates.

- [state.js](https://github.com/renidantass/mapinhaa/blob/main/js/state.js): shared state · Source of truth for round, score, target city, coordinates, API key, and flow flags. · `js/state.js`
- [elements.js](https://github.com/renidantass/mapinhaa/blob/main/js/elements.js): dom handles · Central registry for DOM references and related integration objects. · `js/elements.js`
- [listeners.js](https://github.com/renidantass/mapinhaa/blob/main/js/listeners.js): events · Binds user actions and routes them into logic and UI updates. · `js/listeners.js`
- [logic.js](https://github.com/renidantass/mapinhaa/blob/main/js/logic.js): rules engine · Game rules, round setup, scoring, validation, geocoding, and challenge generation. · `js/logic.js`
- [ui.js](https://github.com/renidantass/mapinhaa/blob/main/js/ui.js): presentation · Updates screens, text, feedback, and visible game states. · `js/ui.js`

### External services

Browser and Google Maps capabilities used by the game.

- **Google Maps API**: maps platform · Maps JavaScript, Street View Static, Geocoding, and Geolocation capabilities.
- **Browser geolocation**: browser API · User location access used to seed or constrain challenges.
- **Canvas effects**: visual layer · HTML5 canvas used for decorative effects.

## Connections

- listeners.js → logic.js: start / guess / next · Event layer invokes game actions based on user input.
- listeners.js → ui.js: feedback · Event layer triggers visible state changes and messaging.
- logic.js → state.js: read / write · Rules engine updates and consumes shared game state.
- ui.js → state.js: render from · Presentation reads shared state to reflect current progress.
- ui.js → elements.js: update dom · UI uses centralized DOM handles to mutate the interface.
- listeners.js → elements.js: bind controls · Listeners attach to shared element references.
- elements.js → index.html: find nodes · Centralized element registry points at the document structure.
- ui.js → style.css: styled by · Interface appearance is driven by the stylesheet.
- ui.js → images: icons / art · Visual UI uses static image assets.
- logic.js → Google Maps API: geocode / street view · Core gameplay depends on external mapping and street-view services.
- logic.js → Browser geolocation: current location · Gameplay can use browser location to seed or constrain rounds.
- logic.js → Canvas effects: effects · Visual effects layer complements the game without changing rules.
- state.js → logic.js: drives flow · Shared flags and round data steer the rule engine.
- state.js → ui.js: drives view · State changes determine what the player sees.
