Documentação de arquitetura
Desenho arquitetural da
plataforma Arah
Modelo C4 completo — Contexto, Containers e Componentes — com diagramas de sequência de todas as funcionalidades implementadas e previstas do app comunitário território-primeiro.
Sistema Plataforma Arah / Araponga
Cliente Flutter + Material 3 (Riverpod)
Servidor API .NET · DDD · REST /v1
Base repo sraphaz/arah
Visão geral
Como ler este documento
O modelo C4 descreve software em quatro níveis de zoom. Aqui cobrimos os três primeiros — do panorama de pessoas e sistemas até os componentes internos — e fechamos com os fluxos de sequência de cada funcionalidade. Tudo é filtrado pelo território ativo: nada é global por padrão.
1Contexto
Quem usa o Arah e com quais sistemas externos ele conversa.
2Containers
As peças executáveis: app, API, banco, realtime, storage.
3Componentes
O interior do app (camadas) e da API (módulos DDD).
sync_altSequências
O passo-a-passo de cada funcionalidade, com endpoints.
Legenda visual
Pessoa / ator
Sistema Arah
Container
Componente
Sistema externo
Chamada
Resposta
GET /endpoint integração
Nível 1 · Contexto do sistema
O Arah e o mundo ao redor
Três papéis humanos — visitante, morador e curador — usam a plataforma a partir do app. O sistema conversa com serviços externos para login, mapas, pagamentos, push e localização. O papel é por território.
personVisitante
Vê o feed público e o mapa do território.
forestMorador
Publica, vende, vota, participa da vida local.
shield_personCurador
Modera, confirma residências, abre eleições.
eco
Plataforma Arah
[Sistema de software]
Extensão digital do território vivo: feed, mapa, eventos, mercado, governança e economia — tudo escopado ao território ativo.
loginGoogle Identity
OAuth / login social
mapOpenStreetMap
Tiles do mapa do território
paymentsProvedor PIX / PSP
Pagamentos & repasses
notifications_activeFCM / APNs
Notificações push
my_locationDispositivo (GPS)
Localização privada
info A localização nunca é exposta a outros usuários — serve apenas para sugerir o território e estimar presença. Visibilidade e papéis são sempre impostos pelo servidor.
Nível 2 · Containers
As peças executáveis
O app fala com a API .NET por REST sobre HTTPS (JWT), recebe tempo-real pelo gateway e envia mídia direto ao storage via URL assinada. A API orquestra banco, storage, workers e os serviços externos.
Clientes
smartphoneApp Mobile
[Flutter · Material 3 · Riverpod]
O produto. Feed, mapa, mercado, jornadas — tudo escopado ao território ativo.
languagePortal Web
[Next.js]
Voz da marca: manifesto, funcionalidades, chamado às comunidades.
Limite do sistema · servidor Arah
dnsAPI Application[.NET · DDD · REST /v1]
Autenticação, escopo territorial, regras de papel/visibilidade, paginar por cursor, idempotência em pagamentos. Expõe os módulos de domínio.
boltRealtime Gateway
[WebSocket / SSE]
Chat, novos posts & alertas, notificações ao vivo.
manufacturingBackground Workers
[Jobs / fila]
Push, reconciliação de pagamento, agregados.
databaseBanco relacional
[PostgreSQL]
Territórios, membros, posts, pedidos, eleições.
folder_openObject Storage
[Blob / S3]
Mídia (fotos), upload por URL assinada.
Serviços externos
loginGoogle Identity
Login social
paymentsPIX / PSP
Pagamentos
notifications_activeFCM / APNs
Push
mapOpenStreetMap
Tiles do mapa
Relações entre containers
| Origem |
Destino |
Protocolo & propósito |
| App Mobile | API Application | HTTPS · REST /v1 · JWT — todas as operações de domínio |
| App Mobile | Realtime Gateway | WebSocket / SSE — chat, novos posts, alertas, notificações |
| App Mobile | Object Storage | PUT direto via URL assinada — upload de mídia |
| App Mobile | OpenStreetMap | HTTPS — tiles do mapa (cache local da região) |
| API Application | Banco relacional | EF Core · SQL — persistência do domínio |
| API Application | Object Storage | Emite URLs assinadas; confirma referência de mídia |
| API Application | Google Identity | OAuth — validação do token social |
| API Application | PIX / PSP | HTTPS — cobrança; recebe webhook de confirmação |
| Background Workers | FCM / APNs | Despacho de push por dispositivo |
| Realtime · Workers | Banco relacional | Leem/gravam estado compartilhado |
Nível 3 · Componentes — App Mobile
Dentro do app Flutter
Arquitetura em quatro camadas (Clean Architecture com Riverpod). A dependência aponta sempre para baixo: a UI consome controllers, que orquestram casos de uso do domínio, que falam com repositórios. A camada de dados une fonte remota e cache local (offline-first).
widgetsPresentationtelas & widgets puros · 4 estados de UI
Telas (Feed, Mapa, Mercado, Perfil…)
TopBar · BottomNav
JourneyShell · SuccessView
Card · Chip · RoleBadge
PixPay · Skeletons
tuneApplicationcontrollers Riverpod · estado de tela · ações otimistas
AuthController
TerritoryController
FeedController
MapController
MarketController
GovernanceController
NotificationController
schemaDomainentidades & casos de uso · independente de framework
Entidades (Territory, Membership, Post, Event, Order, Election…)
Regras de papel & visibilidade
Validações
storageDatarepositórios · remoto + local · stale-while-revalidate
Repositories
API client (dio + interceptors)
Cache local (Drift / Isar)
Outbox offline (gap)
Realtime client
Media uploader
arrow_outward → API .NET (REST)
arrow_outward → Realtime (WS/SSE)
arrow_outward → Object Storage
Transversais
alt_routego_routerRotas tipadas, overlays, deep links.
lockSecure StorageJWT + refresh em Keychain/Keystore.
notificationsPush registryRegistro de token FCM/APNs.
imageImage cachecached_network_image + blurhash.
construction A maior lacuna estrutural é a camada de dados offline-first (cache local + remoto, outbox de ações, revalidação) — deve ser definida antes de escalar as telas.
Nível 3 · Componentes — API .NET
Dentro da API (módulos DDD)
Toda requisição atravessa um pipeline transversal antes de chegar ao módulo de domínio. Cada módulo é um bounded context que persiste via EF Core e publica eventos para realtime, workers e push.
Pipeline de requisição
Controllers /v1
chevron_right
Auth · JWT/refresh
chevron_right
Escopo territorial
chevron_right
Validação & papel
chevron_right
Idempotência
chevron_right
Envelope de erro · cursor
Módulos de domínio • implementados
badgeIdentity & Auth
Login, JWT, refresh, OAuth Google.
forestTerritories
Próximos, fronteira, feature flags.
how_to_regMembership
Papéis, residência, presença.
ecoFeed & Content
Posts, comentários, curtidas, reports.
mapMap & Entities
Pins, lugares, trilhas; curadoria.
eventEvents
Eventos, participação.
storefrontMarketplace
Lojas, itens, carrinho, pedidos.
paymentsPayments
PIX, idempotência, repasse.
how_to_voteGovernance
Eleições, voto secreto.
shield_personModeration
Fila, decisões, sanções, auditoria.
chatMessaging
Conversas e threads.
notificationsNotifications
Inbox, deep-links, despacho.
imageMedia
URLs assinadas, blurhash.
Módulos de economia & serviços • previstos
groups_2Group Buys
Compra coletiva, tiers (F17).
cottageBookings
Hospedagem, bem-estar (F18/E10).
swap_horizEconomy
Demandas, trocas, entregas (F19-21).
account_balance_walletWallet (Aratá)
Moeda territorial (F22).
conciergeServices
Babás, alugáveis, hub digital.
subscriptionsSubscriptions
Apoio recorrente PIX (F15).
schoolLearning & Seeds
Oficinas, banco de sementes (F45/48).
monitoringInsights
Saúde & métricas do território (F24/25).
smart_toyAI Assistant
Chat ancorado nos dados locais (F27).
manufacturingJob dispatcher
Mapa de domínios
Todas as funcionalidades num só desenho
O território escopa tudo; a membership (papel) autoriza cada ação. Os domínios de negócio se agrupam em quatro áreas e se conectam a um barramento de serviços compartilhados — pagamentos, notificações, mídia e tempo-real. Cada chip leva ao fluxo de sequência correspondente.
forestTerritório ativo— escopa feed, mapa, mercado, governança e economia
visitante · morador · curador — rege visibilidade e participação em cada domínio abaixo
storefrontEconomia & mercado
Barramento de serviços compartilhados
paymentsPayments (PIX/PSP)
Mercado, hospedagem, alugéis, assinaturas, carteira.
notificationsNotifications
Alertas, eventos, pedidos, eleições, moderação.
imageMedia
Feed, mapa, perfil, lojas (URLs assinadas).
boltRealtime
Mensagens, feed ao vivo, entregas, push.
Interconexões-chave
hubTerritório → escopa todos os domínios; trocar de território invalida caches e recarrega tudo.
keyMembership → autoriza cada ação por papel; visibilidade é imposta no servidor.
paymentsPayments ← serve mercado, hospedagem, alugéis, assinaturas e carteira (idempotente).
campaignNotifications ← alimentado por alertas, eventos, pedidos, eleições e moderação; resolve deep links.
shield_personCuradoria → governa entidades do mapa, posts sinalizados e confirmação de residência.
boltRealtime → entrega mensagens, novos posts/alertas, posição de entregas e notificações ao vivo.
Implantação
Onde cada peça roda
O app vive no dispositivo (com cache e secure storage); o servidor roda na nuvem; mídia e tiles passam por CDN. Tudo sobre TLS.
smartphoneDispositivo
[iOS / Android]
App MobileFlutter · cache local · outbox
Secure storage
Tiles cache
Provedor de nuvem
dnsAPI .NET
Container · auto-scale
boltRealtime
WS/SSE · sticky
manufacturingWorkers
Fila de jobs
databasePostgreSQL
Banco gerenciado
folder_openObject Storage
Blob/S3 + CDN
shieldGateway / TLS
HTTPS, rate-limit
SaaS externo
loginGoogle Identity
paymentsPIX / PSP
notifications_activeFCM / APNs
mapOpenStreetMap (CDN de tiles)
Diagramas de sequência
Como cada funcionalidade flui
Um fluxo por funcionalidade, com os participantes (ator, app, API, banco, externos) e as chamadas esperadas. Linha cheia = chamada; linha tracejada = resposta. Endpoints são ilustrativos — alinhar com o Swagger do backend.
check_circle Funcionalidades implementadas
{{ d.title }}
{{ d.tag }}
{{ d.summary }}
{{ p.label }}
{{ p.type }}
{{ m.label }} {{ m.endpoint }}
{{ m.label }} {{ m.endpoint }}
{{ m.label }}
schedule Funcionalidades previstas (roadmap)
{{ d.title }}
{{ d.tag }}
{{ d.summary }}
{{ p.label }}
{{ p.type }}
{{ m.label }} {{ m.endpoint }}
{{ m.label }} {{ m.endpoint }}
{{ m.label }}