# staroscky/controle-cancha architecture

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

- Interactive diagram: https://gitdiagram.com/staroscky/controle-cancha
- Repository: https://github.com/staroscky/controle-cancha

## Overview

Controle de Bocha é um aplicativo client-side para acompanhar clientes, partidas, consumo e acerto de contas, com persistência local e uso offline via PWA conforme o README. O fluxo principal vai do operador às telas de gestão, que registram eventos e consultam saldos e históricos. Os hooks amostrados coordenam regras e repositórios; o código não amostrado é representado apenas pelos módulos e capacidades identificáveis na árvore, sem presumir chamadas específicas entre eles.

Main entry points: [`app/src/App.tsx`](https://github.com/staroscky/controle-cancha/blob/main/app/src/App.tsx) (Navegação), [`app/src/ui/hooks/useComandas.ts`](https://github.com/staroscky/controle-cancha/blob/main/app/src/ui/hooks/useComandas.ts) (Comandas), [`app/src/ui/hooks/usePartidaAtiva.ts`](https://github.com/staroscky/controle-cancha/blob/main/app/src/ui/hooks/usePartidaAtiva.ts) (Partida ativa), [`app/src/ui/hooks/useClientes.ts`](https://github.com/staroscky/controle-cancha/blob/main/app/src/ui/hooks/useClientes.ts) (Gestão clientes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Interface"]
  node_app["Navegação<br/>[App.tsx]"]
  node_clients_page["Clientes<br/>[ClientesPage.tsx]"]
  node_match_page["Partidas<br/>[PartidaPage.tsx]"]
  node_consumption_page["Catálogo<br/>[ConsumoPage.tsx]"]
  node_accounts_page["Comandas<br/>[ComandasPage.tsx]"]
  node_stats_page["Estatísticas"]
  node_backup_page["Dados e backup<br/>[BackupPage.tsx]"]
end

subgraph group_operations["Operações"]
  node_clients_hook["Gestão clientes<br/>[useClientes.ts]"]
  node_match_hook["Partida ativa<br/>[usePartidaAtiva.ts]"]
  node_accounts_hook["Comandas<br/>[useComandas.ts]"]
  node_stats_hook["Estatísticas<br/>[useEstatisticas.ts]"]
  node_consumption_hook["Consumo<br/>[useConsumo.ts]"]
end

subgraph group_domain["Regras e dados"]
  node_client_rules["Saldo e clientes<br/>[calcularSaldo.ts]"]
  node_match_rules["Regras de partida"]
  node_consumption_rules["Regras de consumo"]
  node_client_repo["Clientes e grupos<br/>[clientesRepo.ts]"]
  node_match_repo["Partidas e participantes<br/>[partidasRepo.ts]"]
  node_ledger_repo["Lançamentos<br/>[lancamentosRepo.ts]"]
  node_catalog_repo["Catálogo de consumo"]
  node_backup_repo["Backup<br/>[backupRepo.ts]"]
end

subgraph group_persistence["Persistência"]
  node_storage["Armazenamento local<br/>[storage.ts]"]
end

node_operator(("Operador"))
node_localstorage[("LocalStorage")]

node_operator -->|"usa"| node_app
node_app -->|"abre"| node_clients_page
node_app -->|"abre"| node_match_page
node_app -->|"abre"| node_consumption_page
node_app -->|"abre"| node_accounts_page
node_app -->|"abre"| node_stats_page
node_app -->|"abre"| node_backup_page
node_clients_page -->|"consulta"| node_clients_hook
node_match_page -->|"consulta"| node_match_hook
node_accounts_page -->|"consulta"| node_accounts_hook
node_stats_page -->|"consulta"| node_stats_hook
node_consumption_page -->|"consulta"| node_consumption_hook
node_clients_hook -->|"lê e altera"| node_client_repo
node_clients_hook -->|"consulta e remove"| node_ledger_repo
node_clients_hook -->|"calcula saldo"| node_client_rules
node_match_hook -->|"gerencia partida"| node_match_repo
node_match_hook -->|"consulta clientes"| node_client_repo
node_match_hook -->|"registra eventos"| node_ledger_repo
node_match_hook -->|"prepara fechamento"| node_match_rules
node_match_hook -->|"prepara consumo"| node_consumption_rules
node_accounts_hook -->|"consulta clientes"| node_client_repo
node_accounts_hook -->|"consulta participação"| node_match_repo
node_accounts_hook -->|"consulta catálogo"| node_catalog_repo
node_accounts_hook -->|"registra lançamentos"| node_ledger_repo
node_accounts_hook -->|"prepara consumo"| node_consumption_rules
node_accounts_hook -->|"calcula saldo"| node_client_rules
node_backup_page -->|"opera backup"| node_backup_repo
node_client_repo -->|"lê e grava"| node_storage
node_storage -->|"lê e grava"| node_localstorage

click node_app "https://github.com/staroscky/controle-cancha/blob/main/app/src/App.tsx"
click node_clients_page "https://github.com/staroscky/controle-cancha/blob/main/app/src/ui/pages/ClientesPage.tsx"
click node_match_page "https://github.com/staroscky/controle-cancha/blob/main/app/src/ui/pages/PartidaPage.tsx"
click node_consumption_page "https://github.com/staroscky/controle-cancha/blob/main/app/src/ui/pages/ConsumoPage.tsx"
click node_accounts_page "https://github.com/staroscky/controle-cancha/blob/main/app/src/ui/pages/ComandasPage.tsx"
click node_stats_page "https://github.com/staroscky/controle-cancha/blob/main/app/src/ui/pages/EstatisticasPage.tsx"
click node_backup_page "https://github.com/staroscky/controle-cancha/blob/main/app/src/ui/pages/BackupPage.tsx"
click node_clients_hook "https://github.com/staroscky/controle-cancha/blob/main/app/src/ui/hooks/useClientes.ts"
click node_match_hook "https://github.com/staroscky/controle-cancha/blob/main/app/src/ui/hooks/usePartidaAtiva.ts"
click node_accounts_hook "https://github.com/staroscky/controle-cancha/blob/main/app/src/ui/hooks/useComandas.ts"
click node_stats_hook "https://github.com/staroscky/controle-cancha/blob/main/app/src/ui/hooks/useEstatisticas.ts"
click node_consumption_hook "https://github.com/staroscky/controle-cancha/blob/main/app/src/ui/hooks/useConsumo.ts"
click node_client_rules "https://github.com/staroscky/controle-cancha/blob/main/app/src/domain/rules/calcularSaldo.ts"
click node_match_rules "https://github.com/staroscky/controle-cancha/blob/main/app/src/domain/rules/prepararLancamentosFechamentoPartida.ts"
click node_consumption_rules "https://github.com/staroscky/controle-cancha/blob/main/app/src/domain/rules/prepararLancamentosConsumo.ts"
click node_client_repo "https://github.com/staroscky/controle-cancha/blob/main/app/src/data/clientesRepo.ts"
click node_match_repo "https://github.com/staroscky/controle-cancha/blob/main/app/src/data/partidasRepo.ts"
click node_ledger_repo "https://github.com/staroscky/controle-cancha/blob/main/app/src/data/lancamentosRepo.ts"
click node_catalog_repo "https://github.com/staroscky/controle-cancha/blob/main/app/src/data/itensConsumoRepo.ts"
click node_backup_repo "https://github.com/staroscky/controle-cancha/blob/main/app/src/data/backupRepo.ts"
click node_storage "https://github.com/staroscky/controle-cancha/blob/main/app/src/data/storage.ts"

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,node_clients_page,node_match_page,node_consumption_page,node_accounts_page,node_stats_page,node_backup_page toneBlue
class node_clients_hook,node_match_hook,node_accounts_hook,node_stats_hook,node_consumption_hook,node_localstorage toneAmber
class node_client_rules,node_match_rules,node_consumption_rules,node_client_repo,node_match_repo,node_ledger_repo,node_catalog_repo,node_backup_repo toneMint
class node_storage toneRose
class node_operator toneIndigo
```

## Components

### Interface

- [Navegação](https://github.com/staroscky/controle-cancha/blob/main/app/src/App.tsx): `app/src/App.tsx`
- [Clientes](https://github.com/staroscky/controle-cancha/blob/main/app/src/ui/pages/ClientesPage.tsx): `app/src/ui/pages/ClientesPage.tsx`
- [Partidas](https://github.com/staroscky/controle-cancha/blob/main/app/src/ui/pages/PartidaPage.tsx): `app/src/ui/pages/PartidaPage.tsx`
- [Catálogo](https://github.com/staroscky/controle-cancha/blob/main/app/src/ui/pages/ConsumoPage.tsx): `app/src/ui/pages/ConsumoPage.tsx`
- [Comandas](https://github.com/staroscky/controle-cancha/blob/main/app/src/ui/pages/ComandasPage.tsx): `app/src/ui/pages/ComandasPage.tsx`
- [Estatísticas](https://github.com/staroscky/controle-cancha/blob/main/app/src/ui/pages/EstatisticasPage.tsx): `app/src/ui/pages/EstatisticasPage.tsx`
- [Dados e backup](https://github.com/staroscky/controle-cancha/blob/main/app/src/ui/pages/BackupPage.tsx): `app/src/ui/pages/BackupPage.tsx`

### Operações

- [Gestão clientes](https://github.com/staroscky/controle-cancha/blob/main/app/src/ui/hooks/useClientes.ts): `app/src/ui/hooks/useClientes.ts`
- [Partida ativa](https://github.com/staroscky/controle-cancha/blob/main/app/src/ui/hooks/usePartidaAtiva.ts): `app/src/ui/hooks/usePartidaAtiva.ts`
- [Comandas](https://github.com/staroscky/controle-cancha/blob/main/app/src/ui/hooks/useComandas.ts): `app/src/ui/hooks/useComandas.ts`
- [Estatísticas](https://github.com/staroscky/controle-cancha/blob/main/app/src/ui/hooks/useEstatisticas.ts): `app/src/ui/hooks/useEstatisticas.ts`
- [Consumo](https://github.com/staroscky/controle-cancha/blob/main/app/src/ui/hooks/useConsumo.ts): `app/src/ui/hooks/useConsumo.ts`

### Regras e dados

- [Saldo e clientes](https://github.com/staroscky/controle-cancha/blob/main/app/src/domain/rules/calcularSaldo.ts): `app/src/domain/rules/calcularSaldo.ts`
- [Regras de partida](https://github.com/staroscky/controle-cancha/blob/main/app/src/domain/rules/prepararLancamentosFechamentoPartida.ts): `app/src/domain/rules/prepararLancamentosFechamentoPartida.ts`
- [Regras de consumo](https://github.com/staroscky/controle-cancha/blob/main/app/src/domain/rules/prepararLancamentosConsumo.ts): `app/src/domain/rules/prepararLancamentosConsumo.ts`
- [Clientes e grupos](https://github.com/staroscky/controle-cancha/blob/main/app/src/data/clientesRepo.ts): `app/src/data/clientesRepo.ts`
- [Partidas e participantes](https://github.com/staroscky/controle-cancha/blob/main/app/src/data/partidasRepo.ts): `app/src/data/partidasRepo.ts`
- [Lançamentos](https://github.com/staroscky/controle-cancha/blob/main/app/src/data/lancamentosRepo.ts): `app/src/data/lancamentosRepo.ts`
- [Catálogo de consumo](https://github.com/staroscky/controle-cancha/blob/main/app/src/data/itensConsumoRepo.ts): `app/src/data/itensConsumoRepo.ts`
- [Backup](https://github.com/staroscky/controle-cancha/blob/main/app/src/data/backupRepo.ts): `app/src/data/backupRepo.ts`

### Persistência

- [Armazenamento local](https://github.com/staroscky/controle-cancha/blob/main/app/src/data/storage.ts): `app/src/data/storage.ts`

### Other components

- **Operador**
- **LocalStorage**

## Connections

- Operador → Navegação: usa
- Navegação → Clientes: abre
- Navegação → Partidas: abre
- Navegação → Catálogo: abre
- Navegação → Comandas: abre
- Navegação → Estatísticas: abre
- Navegação → Dados e backup: abre
- Clientes → Gestão clientes: consulta
- Partidas → Partida ativa: consulta
- Comandas → Comandas: consulta
- Estatísticas → Estatísticas: consulta
- Catálogo → Consumo: consulta
- Gestão clientes → Clientes e grupos: lê e altera
- Gestão clientes → Lançamentos: consulta e remove
- Gestão clientes → Saldo e clientes: calcula saldo
- Partida ativa → Partidas e participantes: gerencia partida
- Partida ativa → Clientes e grupos: consulta clientes
- Partida ativa → Lançamentos: registra eventos
- Partida ativa → Regras de partida: prepara fechamento
- Partida ativa → Regras de consumo: prepara consumo
- Comandas → Clientes e grupos: consulta clientes
- Comandas → Partidas e participantes: consulta participação
- Comandas → Catálogo de consumo: consulta catálogo
- Comandas → Lançamentos: registra lançamentos
- Comandas → Regras de consumo: prepara consumo
- Comandas → Saldo e clientes: calcula saldo
- Dados e backup → Backup: opera backup
- Clientes e grupos → Armazenamento local: lê e grava
- Armazenamento local → LocalStorage: lê e grava