Araponga API • Developer Portal

Araponga API — Territory-first, community-first.

Araponga é uma plataforma comunitária orientada a território: uma célula territorial que organiza contexto, visibilidade e responsabilidade. Este portal apresenta a visão do produto, seus domínios e fluxos, e como contribuir com uma API construída com privacidade por design, governança local e compromisso explícito com cuidado e finalidade dos dados.

Rodar localmente (Swagger) GitHub
Swagger & Health: são recursos do backend local/dev. Rode a API em Development para acessar a documentação interativa e o health check com segurança.
Nota prática: a antiga página inicial tinha o botão “Carregar dados”. A partir daqui, a exploração do território acontece via API: use os exemplos e fluxos abaixo para testar, validar contratos e orientar as próximas iterações.

Sumário

Product brief Domínios Fluxos principais Quickstart Exemplos de API Princípios e governança Design & Coerência Apoio Links úteis

Product brief

O Araponga organiza a comunicação local para moradores, visitantes e iniciativas comunitárias. Ele é usado por pessoas, coletivos e serviços que precisam publicar avisos, eventos e atualizações com contexto territorial. O território é a célula territorial que organiza a experiência, define contexto e estabelece prioridade. A partir dela, visitante e morador determinam regras de visibilidade e acesso.

O Araponga entrega um feed territorial com postagens e eventos, além de um mapa derivado do conteúdo e das entidades locais. Isso prioriza relevância, reforça confiança sobre o que aparece e sustenta memória territorial e eventos locais — com mídias ancoradas em coordenadas quando fizer sentido.

Foco técnico: arquitetura orientada a domínios, contratos simples e auditáveis, governança em camadas e evolução incremental (MVP → camadas avançadas → experiências espaciais ancoradas em território). O objetivo é construir um núcleo sólido antes de acelerar funcionalidades.
Exemplo prático (Feed + Eventos + Mapa): em uma célula territorial, um morador publica um evento comunitário (mutirão, roda de conversa, aviso de trilha). O backend registra o conteúdo associado ao território e à visibilidade (público / restrito / residentes). O app consome o feed territorial filtrado pela célula e pelo papel do usuário (visitor/resident), priorizando relevância local. Quando há referência geográfica, esse conteúdo também é projetado no mapa como entidade territorial, conectando feed e mapa em uma experiência situada com contexto claro e regras explícitas.

Domínios

Os domínios existem para manter responsabilidades claras e evitar que regras sociais se misturem com representações do território. A intenção é proteger a integridade do sistema: território como referência, pessoas como vínculo, conteúdo como expressão, e governança como camada explícita. Abaixo estão os elementos essenciais no estágio atual.

Território

O que é: célula territorial neutra — a referência organizadora do Araponga.

Por que existe: separa “onde” (território) de “quem” (pessoas e vínculos) e de “o quê” (conteúdo e camadas). Isso permite evoluir sem distorcer o conceito base.

  • Campos: id, name, slug, bounds, createdAt.
  • Endpoints: GET /api/v1/territories, GET /api/v1/territories/{id}.

Usuário

O que é: identidade autenticada para agir no sistema.

Por que existe: responsabiliza ações sem depender de exposição de dados sensíveis. A regra é: coletar o mínimo necessário, manter rastreabilidade do que importa e proteger o que não precisa existir.

  • Campos: id, displayName, email, status.
  • Endpoints: POST /api/v1/auth/login, POST /api/v1/auth/register.

Vínculo

O que é: vínculo entre pessoa e território (visitante ou morador).

Por que existe: governa visibilidade, acesso e prioridades locais. Esse domínio é o “coração operacional” das regras: sem ele, o território vira um filtro genérico; com ele, o território vira contexto de convivência.

  • Campos: id, userId, territoryId, role, status.
  • Endpoints: GET /api/v1/territories/{territoryId}/membership.

Feed

O que é: stream de postagens, alertas e eventos filtrados por território e visibilidade.

Por que existe: prioriza relevância local com regras claras. Eventos são um tipo de conteúdo do feed, com janela temporal e impacto no mapa. O feed é territorial para manter contexto, confiança e organização local.

  • Campos: id, title, content, type, visibility, createdAtUtc.
  • Endpoints: GET /api/v1/feed, POST /api/v1/feed.

Mapa

O que é: entidades e camadas georreferenciadas do território.

Por que existe: transforma informação em referência espacial. O mapa é uma projeção territorial derivada de conteúdo e cadastros, conectando o que aparece no feed às entidades locais visíveis e navegáveis.

  • Campos: id, name, category, status, visibility, createdAtUtc.
  • Endpoints: GET /api/v1/map/entities, POST /api/v1/map/entities.

Media + GeoAnchor

O que é: mídia (foto/áudio/vídeo) ancorada em latitude/longitude (e, quando útil, altitude).

Por que existe: constrói memória territorial com precisão — e com controle. GeoAnchor cria base para camadas futuras: visualização contextual, trilhas, registros de cuidado, e eventualmente representações espaciais mais complexas (inclusive 3D) geradas a partir de dados e mídias do app.

  • Campos: mediaId, territoryId, lat, lon, altitude, visibility.
  • Endpoints: planejados (upcoming).

Fluxos principais

Dois fluxos definem a experiência inicial. O sistema resolve visibilidade, prioriza contexto local e entrega respostas consistentes para cliente e API.

Fluxo 1 — Onboarding

  1. Login ou criação de conta.
  2. Escolha de território (ou definição via contexto local, quando aplicável).
  3. Declaração de vínculo: visitante ou morador.
  4. Resolução de visibilidade: o sistema filtra feed e mapa pelo papel e território ativo.

Resultado: o usuário entra em um território como contexto real, com regras explícitas de convivência e acesso aplicadas desde o início.

Fluxo 2 — Post georreferenciado

  1. Criar post no feed do território.
  2. Anexar mídia com geoAnchor (lat/lon/alt) quando for relevante.
  3. Definir visibilidade (público, restrito, moradores).
  4. Distribuição coerente: a API publica no feed e, quando aplicável, no mapa local.

Este fluxo está em construção; a etapa de mídia/geoAnchor é futura. A implementação deve priorizar: privacidade, controle de visibilidade e consistência dos contratos.

Quickstart

Comece localmente ou via Docker. Estes comandos são copy/paste. Dica: valide primeiro /health, depois abra o Swagger, e só então teste os fluxos.

Local (dotnet)

git clone https://github.com/sraphaz/araponga.git
cd araponga

dotnet restore

dotnet run --project backend/Araponga.Api

Abra http://localhost:8080/ (portal) e /swagger (documentação). A porta pode variar conforme a configuração.

Docker

docker build -t araponga-api .

docker run --rm -p 8080:8080 \
  -e ASPNETCORE_URLS=http://0.0.0.0:8080 \
  -e ASPNETCORE_ENVIRONMENT=Development \
  araponga-api

Use ASPNETCORE_ENVIRONMENT=Development para habilitar o Swagger localmente. Em produção, avalie expor Swagger apenas em redes internas ou com autenticação.

Exemplos de API

Use um territoryId real retornado pelo endpoint de territórios. O princípio é simples: descobrir o território, consumir o feed filtrado e carregar o mapa local.

Listar territórios

curl -s http://localhost:8080/api/v1/territories | jq

Use este endpoint para obter o territoryId e a célula territorial que o cliente precisa renderizar.

Listar feed do território

curl -s "http://localhost:8080/api/v1/feed?territoryId=SEU_TERRITORY_ID" | jq

O endpoint retorna um stream filtrado por território e visibilidade. Se houver regras aplicadas por vínculo, teste com perfis visitante e morador para validar o comportamento.

Listar mapa do território

curl -s "http://localhost:8080/api/v1/map/entities?territoryId=SEU_TERRITORY_ID" | jq

Retorna entidades georreferenciadas para compor a camada local do mapa no cliente.

Listar mídia do território (planejado)

# upcoming endpoint
curl -s "http://localhost:8080/api/v1/media?territoryId=SEU_TERRITORY_ID" | jq

A camada de mídia/geoAnchor deve nascer com controle de visibilidade e finalidade explícita: memória territorial com cuidado e contexto.

Postar mídia georreferenciada (planejado)

curl -X POST "http://localhost:8080/api/v1/media" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -F "territoryId=SEU_TERRITORY_ID" \
  -F "lat=-23.5505" \
  -F "lon=-46.6333" \
  -F "visibility=RESIDENT" \
  -F "file=@/caminho/arquivo.jpg"

Planejado para próximas iterações. Prioridade: contratos claros, validações fortes (lat/lon/alt), e proteção de conteúdo sensível.

Princípios e governança

O Araponga orienta decisões técnicas e de produto para fortalecer autonomia local e tratamento cuidadoso de dados. Estes princípios guiam a evolução do produto.

Quer contribuir? Veja CONTRIBUTING.md , leia Design & Coerência ou abra uma issue no GitHub com contexto, motivação e critérios de validação.

Design & Coerência

O guia de Design & Coerência explica como o Araponga preserva foco, calma e clareza visual. Ele existe para orientar contribuições que fortalecem o território como referência e mantêm continuidade na experiência.

Ler o guia de design

Apoie o Araponga

O Araponga é um projeto comunitário, aberto e orientado ao território. Ele existe para sustentar relações locais, cuidado contínuo e autonomia, com contribuição direta e uso responsável de dados.

Se este trabalho ressoa com você, é possível apoiar de forma voluntária, consciente e direta — como quem cuida de um espaço comum para que siga vivo.

PIX (Brasil)

Contribuição direta, sem taxas e sem intermediários. Ideal para apoiar a continuidade de forma simples e soberana.

Chave PIX:
rapha.sos@gmail.com

GitHub Sponsors

Apoie o desenvolvimento técnico, a manutenção da API e a evolução do Araponga como infraestrutura comunitária.

Apoiar no GitHub

Toda contribuição sustenta infraestrutura, documentação, tempo de cuidado e a evolução contínua do Araponga.