Guia do Sistema — Para Humanos
Tudo que você precisa saber sobre a plataforma, sem enrolação.
Usuários da plataforma: existe também um Manual de Uso — a versão não técnica, orientada a tarefas, para donos, administradores, moderadores e membros. Este guia ainda respira desenvolvimento (termos de modelo, permissões detalhadas); o manual é o lugar certo para quem não é desenvolvedor.
O Que É Esta Plataforma?
Imagine uma comunidade online como o Circle.so ou o Discord, mas com tudo organizado em "espaços" temáticos. As pessoas se juntam, postam conteúdo, comentam, participam de eventos, fazem cursos e conversam entre si.
Cada "comunidade" é como um clube independente — com seus próprios membros, regras e conteúdo. Uma pessoa pode participar de várias comunidades ao mesmo tempo.
Conceitos Principais
🏠 Comunidade (Community)
É o "clube" principal. Cada comunidade tem:
- Nome e endereço próprio (subdomínio como
minha-comunidade.plataforma.comou domínio próprio) - Um dono (o criador)
- Membros com diferentes níveis de permissão
- Espaços onde o conteúdo é organizado
Exemplo: "Comunidade de Fotógrafos" em fotografia.plataforma.com
👥 Membros (Membership)
Quando alguém entra numa comunidade, ele vira um membro. Cada membro possui um papel (role) e permissões na plataforma.
Matriz Completa de Permissões e Privilégios
| Categoria | Ação / Recurso | Admin | Moderador (Comunidade) | Moderador de Espaço (SpaceModerator) | Membro Comum |
|---|---|---|---|---|---|
| Spaces & Cursos | Criar, editar ou excluir Spaces e Grupos (SpaceGroups) | ✅ | ✅ | ❌ | ❌ |
| Criar, editar ou excluir Módulos, Aulas e Tags | ✅ | ✅ | ❌ | ❌ | |
| Acessar Spaces Privados e Secretos sem convite | ✅ | ✅ | ❌ | ❌ | |
| Nomear / gerenciar moderadores locais de um Space | ✅ | ✅ | ❌ | ❌ | |
| Posts & Conteúdo | Criar, editar ou apagar os próprios posts e comentários | ✅ | ✅ | ✅ | ✅ |
| Editar ou apagar posts/comentários de outros membros | ✅ | ✅ | ✅ (apenas no Space designado) | ❌ | |
| Fixar (pin) e Trancar (lock) posts | ✅ | ✅ | ✅ (apenas no Space designado) | ❌ | |
| Comentar em posts trancados (locked) | ✅ | ✅ | ✅ (apenas no Space designado) | ❌ | |
| Acessar e gerenciar a Fila de Denúncias (Mod Queue / Reports) | ✅ | ✅ | ❌ | ❌ | |
| Ler, editar ou apagar Mensagens Diretas (DMs) alheias | ❌ (Privacidade) | ❌ (Privacidade) | ❌ (Privacidade) | ❌ (Apenas remetente) | |
| Membros & Moderação | Banir ou desbanir Membros Comuns (MEMBER) | ✅ | ✅ | ❌ | ❌ |
Silenciar (mute) Membros Comuns (MEMBER) | ✅ | ✅ | ❌ | ❌ | |
| Banir, silenciar ou alterar cargo de Moderadores | ✅ | ❌ (Hierarquia) | ❌ | ❌ | |
| Banir ou silenciar Admins | ✅ | ❌ (Hierarquia) | ❌ | ❌ | |
| Despromover Admins (alterar o cargo de um admin para moderador/membro) | ❌ (só o dono da comunidade) | ❌ (Hierarquia) | ❌ | ❌ | |
| Banir ou silenciar a si próprio | ❌ | ❌ | ❌ | ❌ | |
| Alterar configurações gerais da comunidade / tenant | ✅ | ❌ | ❌ | ❌ |
Status do membro:
- Ativo — pode usar normalmente
- Convidado — ainda não aceitou o convite
- Banido — não pode acessar a comunidade
Um membro também pode ser silenciado (muted) temporariamente (não pode postar nem comentar).
📁 Espaços (Space)
São as "salas" onde o conteúdo vive. Os espaços ficam organizados em Seções (SpaceGroups) na barra lateral — por exemplo, "Comunidade", "Aprendizado", "Eventos". Cada espaço tem um tipo que define o que pode ser feito lá:
| Tipo | O que é | O que acontece lá |
|---|---|---|
| Básico | Fórum | Pessoas postam e comentam |
| Chat | Bate-papo | Mensagens em tempo real |
| Evento | Agenda | Eventos com data, hora e local |
| Curso | Escola | Módulos e aulas com progresso |
| Imagens | Galeria | Pessoas compartilham fotos |
| Membros | Diretório | Lista de membros da comunidade |
| Produto Digital | Loja de arquivos | Lista de tablaturas/presets/MIDI/sample packs pra baixar, paga por pacote |
Níveis de acesso:
- Público — todos os membros podem ver
- Privado — aparece na lista mas precisa de permissão pra acessar
- Secreto — só aparece pra quem tem permissão explícita
📝 Posts
O conteúdo principal em espaços do tipo Básico. Uma pessoa escreve um post, e outras podem:
- Curtir/comentar com reações (❤️ like, 🎉 celebrate, 💡 insightful, etc.)
- Comentar com respostas (máximo 1 nível de profundidade)
- O post pode ser fixado (aparece no topo) ou trancado (sem novos comentários)
- Posts podem ter tags para organização
💬 Chat
Em espaços do tipo Chat, as mensagens são em tempo real. É como um canal de Discord:
- Mensagens aparecem instantaneamente
- Pessoas podem editar ou deletar suas mensagens
- Moderadores também podem deletar
📅 Eventos
Em espaços do tipo Evento, pessoas criam eventos com:
- Título e descrição
- Data de início e fim
- Timezone
- Link de reunião virtual (Zoom, Meet, etc.) ou local físico
- Pessoas confirmam presença (RSVP): "Vou", "Interessado", "Não vou"
🎓 Cursos
Em espaços do tipo Curso, o conteúdo é organizado em módulos e aulas:
Curso
├── Módulo 1
│ ├── Aula 1.1
│ ├── Aula 1.2
│ └── Aula 1.3
├── Módulo 2
│ ├── Aula 2.1
│ └── Aula 2.2Cada pessoa tem um progresso — aulas concluídas ficam marcadas.
🎸 Produtos Digitais (Materiais)
Em espaços do tipo Produto Digital, o conteúdo é uma lista simples de itens — sem módulos/aulas como no Curso. Cada item é um arquivo pra baixar: tablatura, preset, MIDI ou sample pack, com metadados próprios (afinação, dificuldade, instrumento, tom para tabs; DAW, plugin, gênero para presets/samples).
Cada item pode ter vídeos anexados — vídeo de execução, aula, versão lenta, versão rápida, ou qualquer outro papel (é só um texto livre, não uma lista fixa de opções).
O pacote inteiro é pago via Paywall (igual Curso). Quem não comprou vê a lista bloqueada — exceto os itens marcados como grátis, que ficam abertos (arquivo + vídeos) mesmo sem comprar, como amostra do pacote.
🖼️ Galeria de Imagens
Em espaços do tipo Imagem, pessoas compartilham fotos com legendas. As imagens podem receber reações (curtidas).
💌 Mensagens Diretas (DMs)
Pessoas podem conversar particularmente uma com a outra. O sistema garante que:
- Cada par de pessoas tem apenas uma conversa (não importa quem iniciou)
- As mensagens podem ser editadas ou deletadas
- Moderadores não podem ler DMs (privacidade garantida)
🏷️ Tags
São etiquetas que organizam os posts. Exemplos: "Dúvida", "Dica", "Discussão". Cada comunidade cria suas próprias tags.
⭐ Reações
Emoji que colocamos em posts, comentários ou imagens:
| Emoji | Nome | Significado |
|---|---|---|
| 👍 | like | Gostei |
| ❤️ | love | Amei |
| 🎉 | celebrate | Celebrei |
| 🤝 | support | Apoiei |
| 💡 | insightful | Interessante |
| 🤔 | curious | Curioso |
🚩 Reports (Denúncias)
Se alguém vê conteúdo inadequado, pode denunciar. Motivos:
- Spam — conteúdo indesejado
- Assédio — bullying, ofensas
- Fora do tópico — conteúdo irrelevante
- Outro — outro motivo
Os moderadores recebem as denúncias e decidem se resolvem ou dispensam.
🏆 Gamificação (Pontos e Níveis)
A plataforma incentiva a participação com pontos:
| Ação | Pontos |
|---|---|
| Criar um post | +10 |
| Criar um comentário | +5 |
| Completar uma aula | +15 |
Níveis:
| Nível | Pontos necessários |
|---|---|
| 🥉 Nível 1 | 0 |
| 🥈 Nível 2 | 100 |
| 🥇 Nível 3 | 300 |
| 💎 Nível 4 | 700 |
| 👑 Nível 5 | 1500 |
Existe um ranking (leaderboard) na comunidade mostrando quem tem mais pontos.
👤 Perfil Customizado
Cada comunidade pode criar campos extras no perfil dos membros. Por exemplo:
- "Empresa" (texto)
- "Cargo" (seleção: Designer, Dev, PM, etc.)
- "LinkedIn" (URL)
- "Data de entrada" (data)
Os membros preenchem esses campos no perfil.
🔐 Grupos (Access Groups)
São "equipes" ou "turmas" dentro da comunidade. Podem ser usados para:
- Limitar quem vê um space específico
- Criar conteúdos exclusivos para certos membros
Exemplo: "Alunos Premium" é um grupo. O space "Conteúdo Exclusivo" só é acessível para membros desse grupo.
🌐 Internacionalização (Idiomas, Fuso Horário e Moeda)
A comunidade suporta múltiplos idiomas e fusos horários:
- Idioma Principal da Comunidade: Define a linguagem padrão do tenant (ex:
pt-BR,en-US,es). - Recurso Multilíngue (Multilingual): Permite cadastrar traduções para nomes de Espaços, Cursos, Módulos, Aulas, Posts e Anúncios.
- Resolução Automática: Ao acessar a comunidade via API ou navegador, o sistema identifica a preferência do usuário (via URL
?lang=...ou cabeçalho do navegadorAccept-Language) e entrega o conteúdo traduzido. Se não houver tradução para o idioma solicitado, o sistema faz o fallback automático para o idioma original. - Moeda e Fuso Horário: Cada comunidade define sua moeda padrão para pagamentos/paywalls (ex:
BRL,USD) e seu fuso horário (ex:America/Sao_Paulo).
🛡️ Moderadores de Space
Além dos admins e moderadores da comunidade inteira, pode-se designar moderadores específicos de um space. Essas pessoas só têm poder de moderação naquele espaço específico.
🔌 Protocolo MCP (Model Context Protocol)
O protocolo MCP permite que assistentes de IA (como Claude, ChatGPT ou outros agentes virtuais) se conectem à plataforma para realizar consultas e tarefas de gerenciamento de forma direta e segura.
Como funciona:
- Autenticação por Chave de API: O assistente de IA se conecta enviando uma chave de API MCP (
MCPApiKey). - Vínculo por Membro (Tenant Scoped): Cada chave MCP é criada para um membro específico dentro de uma comunidade (
Membership). - Respeito às Permissões: Todas as ações executadas pela IA respeitam exatamente o nível de acesso da chave: se pertence a um membro comum, a IA só pode visualizar e criar o que aquele membro pode. Se pertence a um admin ou moderador, a IA tem acesso às funções administrativas.
- Ferramentas Integradas (Tools): A IA pode consultar informações da comunidade, listar e criar espaços, buscar e publicar posts, gerenciar comentários e consultar perfis de membros através das ferramentas do servidor MCP.
Fluxos Comuns
1. Como uma pessoa entra numa comunidade?
- Recebe um link de convite por email
- Cria uma conta (ou faz login se já tem)
- O convite é aceito automaticamente
- Vira um membro ativo da comunidade
2. Como criar um post?
- Entra num space do tipo "Básico"
- Clica em "Novo Post"
- Escreve o conteúdo
- Adiciona tags (opcional)
- Publica
3. Como participar de um evento?
- Entra num space do tipo "Evento"
- Vê a lista de eventos
- Clica num evento
- Confirma presença: "Vou", "Interessado" ou "Não vou"
4. Como fazer um curso?
- Entra num space do tipo "Curso"
- Vê os módulos e aulas
- Clica numa aula
- Estuda o conteúdo
- Marca como "Concluída"
- Ganha +15 pontos!
5. Como denunciar conteúdo inadequado?
- Encontra o post/comentário/imagem/chat que viola as regras
- Clica em "Denunciar"
- Escolhe o motivo
- Adiciona detalhes (opcional)
- A denúncia vai para a fila de moderação
Regras de Negócio Importantes
Multi-tenancy
- Cada comunidade é isolada. Membros de uma comunidade não veem o conteúdo de outra.
- O sistema identifica a comunidade pelo endereço (subdomínio ou domínio próprio).
Quem pode fazer o quê?
| Ação | Admin | Moderador | Membro |
|---|---|---|---|
| Criar spaces | ✅ | ❌ | ❌ |
| Deletar qualquer conteúdo | ✅ | ✅ | ❌ |
| Silenciar membros | ✅ | ✅ | ❌ |
| Banir membros | ✅ | ✅ | ❌ |
| Criar posts | ✅ | ✅ | ✅ |
| Comentar | ✅ | ✅ | ✅ |
| Denunciar | ✅ | ✅ | ✅ |
| Ver fila de moderação | ✅ | ✅ | ❌ |
| Gerenciar config da comunidade | ✅ | ❌ | ❌ |
Restrições de Conteúdo
- Posts só podem ser criados em spaces do tipo "Básico"
- Comentários têm máximo 1 nível de profundidade (resposta de resposta não pode ter resposta)
- Posts trancados não recebem novos comentários
- Membros silenciados não podem criar posts, comentários ou enviar mensagens
- DMs são privadas — nem moderadores podem ler
Soft-delete
- Chat e DMs usam "soft-delete" — a mensagem fica marcada como deletada mas o registro permanece (para moderação e para que o WebSocket saiba que foi removida)
- Todo o resto usa "hard-delete" — o registro é removido permanentemente
Imagens
- Formatos aceitos: imagens (JPEG, PNG, GIF, etc.)
- Tamanho máximo: 5 MB
- Upload via S3 (compatível com MinIO)
Segurança
- JWT com validade de 30 minutos (access) e 14 dias (refresh)
- Tokens WebSocket são de uso único e expiram em 30 segundos
- Rate limiting: 1000 requisições/hora por usuário, 5000/hora por API key
- API keys têm escopos de permissão
Glossário
| Termo | Significado |
|---|---|
| Community | A "comunidade" ou "clube" principal |
| Membership | A adesão de um usuário a uma comunidade |
| Space | Uma "sala" onde o conteúdo vive |
| Seção (SpaceGroup) | Um agrupamento de spaces na sidebar (ex: "Comunidade", "Aprendizado") |
| Post | Uma publicação de texto num space básico |
| Comment | Um comentário num post |
| Event | Um evento com data e hora |
| RSVP | Confirmação de presença num evento |
| Module | Uma seção de um curso |
| Lesson | Uma aula dentro de um módulo |
| LessonProgress | Registro de conclusão de uma aula |
| ChatMessage | Uma mensagem num chat ao vivo |
| DMThread | Uma conversa particular entre duas pessoas |
| DMMessage | Uma mensagem numa conversa particular |
| Reaction | Uma reação (curtida) em conteúdo |
| Report | Uma denúncia de conteúdo inadequado |
| Tag | Uma etiqueta para organizar posts |
| Grupo (AccessGroup) | Um grupo de membros com acesso a conteúdos exclusivos |
| APIKey | Uma chave de acesso para integrações externas |
| MCPApiKey | Chave de API para autenticação de assistentes de IA no Servidor MCP |
| FastMCP | Framework Python para construção do servidor MCP integrado ao Django via ASGI |
| PointTransaction | Um registro de pontos ganhos |
| ProfileFieldDefinition | Um campo customizado do perfil |
| ProfileFieldValue | O valor preenchido num campo do perfil |
| SpaceModerator | Um moderador com permissão apenas num space específico |
| Bookmark | Um post salvo/favoritado por um usuário |
| PostFollower | Um usuário que segue um post (recebe notificações de novos comentários) |
| ChatRoom | Uma sala de chat (DM ou grupo) |
| ChatRoomMember | Um membro de uma sala de chat |
| ChatRoomMessage | Uma mensagem numa sala de chat |
| Tenant | O conceito de "inquilino" — cada comunidade é um tenant isolado |
| Generic FK | Campo que pode apontar para diferentes tipos de modelo (ex: Reaction pode ser em Post, Comment ou Image) |
| Soft-delete | Marcar algo como deletado sem remover do banco |