# miltchola/quiz-distribuido architecture

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

- Interactive diagram: https://gitdiagram.com/miltchola/quiz-distribuido
- Repository: https://github.com/miltchola/quiz-distribuido

## Overview

Para guiar o engenheiro sênior na criação de um diagrama de arquitetura claro, completo e específico para este projeto de “Quiz Distribuído”, siga as instruções abaixo, estruturadas em etapas:

##### Identificação do Tipo de Projeto e Propósito
- Trata-se de uma aplicação **cliente-servidor distribuída** em Python, cujo objetivo é permitir que múltiplos clientes (jogadores) se conectem a servidores especializados em categorias de quiz distintas (tecnologia, filmes, futebol, jogos).
- O foco está na **interoperabilidade**: clientes e servidores distintos devem poder comunicar-se via um protocolo JSON/TCP padronizado.

##### Análise da Estrutura de Arquivos
- Top-level:
- README.md, backlog.md
- Diretórios: `client/`, `server/`, `shared/`
- client/src/main.py
- Responsável pela interface CLI do jogador, captura respostas e exibe feedback/resultados.
- server/src/
- `main.py`: entrypoint do servidor, recebe params (categoria, porta).
- `game_manager.py`: componente central de lógica de jogo — mantém estado de jogadores, questões, pontuações.
- `question_loader.py`: carrega arquivos JSON de `server/src/questions/`.
- `questions/*.json`: repositório de perguntas por categoria.
- shared/protocol.py
- Classes/enum ou constantes de mensagens (`connect`, `question`, `answer`, `feedback`, `result`, `error`).

##### Pontos Chave do README
- Descrição clara dos componentes: **QuizServer**, **QuizClient**, **GameManager**.
- Protocolo de comunicação: **JSON sobre sockets TCP**.
- Fluxo de execução:
1. Inicia servidor com categoria e porta.
2. Conecta cliente usando host, porta e nome do jogador.
- Tecnologias principais: Python 3.x, bibliotecas padrão (`socket`, `json`, `threading`).

##### Como Criar o Diagrama de Arquitetura
a. Componentes Principais
- Cliente (QuizClient CLI)
- Rede TCP/IP
- Servidor (QuizServer)
- Módulo de aceitação de conexões (TCP socket listener)
- GameManager (estado do jogo, lógica de fluxo)
- QuestionLoader + Armazenamento JSON
- Shared/Protocolo (definição de mensagens)
b. Relacionamentos e Fluxos
- Setas bidirecionais entre Cliente e Servidor (camada TCP) carregando payloads JSON.
- Internamente, o Servidor chama QuestionLoader → retorna lista de questões → GameManager gerencia envio de “question” → recebe “answer” → calcula e envia “feedback” → ao término envia “result”.
c. Padrões e Princípios Arquiteturais
- **Separação de responsabilidades**:
- Interface de rede + parsing JSON
- Lógica de jogo isolada (GameManager)
- Persistência de dados leve (JSON como datastore)
- **Protocolo padronizado** (Shared module) para garantir interoperabilidade
- Uso de **threading** no servidor para suportar múltiplos clientes concorrentes
d. Tecnologias e Bibliotecas
- Python 3.x
- socket (server/client TCP)
- json (serialização de mensagens)
- threading (concorrência no servidor)

##### Diretrizes de Ajuste para este Projeto
- Não é um sistema full-stack web, mas sim um serviço de rede distribuído.
- Destaque no diagrama:
- Cliente leve → interface de linha de comando
- Servidor concorrente → thread pool ou modelagem de threads por conexão
- QuestionLoader isolado do GameManager
- Shared/protocol.py destacando o contrato de mensagens

##### Elementos Gráficos Essenciais
- Componentes com rótulos claros (“QuizClient”, “TCP Socket”, “QuizServer”, “GameManager”, “QuestionLoader”, “Questions JSON”, “Protocol Definitions”).
- Setas direcionais codificando fluxo de dados:
- → welcome → question → answer → feedback → result
- Cores ou formas distintas:
- Azul para componentes de rede (Sockets)
- Verde para lógica de aplicação (GameManager)
- Laranja para persistência/arquivos (JSON)
- Cinza para componentes de compartilhamento/protocolo

##### Atenção aos Detalhes
- Cada mensagem do protocolo deve estar anotada ao longo da seta correspondente.
- Mostre a thread handling no servidor (por exemplo, subset de threads recebendo conexões).
- Indique claramente onde e como as questões JSON são carregadas (QuestionLoader → injeção no GameManager).
- Inclua uma legenda para cores e símbolos escolhidos.

Seguindo estes passos, o diagrama resultante será completo, refletindo fielmente a arquitetura distribuída do Quiz e enfatizando a interoperabilidade via protocolo JSON/TCP e a modularização interna do servidor.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    QuizClient["QuizClient CLI"]:::client
    click QuizClient "https://github.com/miltchola/quiz-distribuido/blob/main/client/src/main.py"

    %% Network Layer
    TCPSocket["TCP Socket"]:::network

    %% Shared Protocol
    Protocol["Protocol Definitions\n(JSON/TCP Contracts)"]:::shared
    click Protocol "https://github.com/miltchola/quiz-distribuido/blob/main/shared/protocol.py"

    %% Server Layer
    subgraph "QuizServer"
        direction TB
        ConnectionListener["Connection Listener\n(TCP Socket Listener)"]:::network
        GameManager["GameManager\n(Game State & Logic)"]:::logic
        click GameManager "https://github.com/miltchola/quiz-distribuido/blob/main/server/src/game_manager.py"
        QuestionLoader["QuestionLoader\n(Loads JSON Questions)"]:::logic
        click QuestionLoader "https://github.com/miltchola/quiz-distribuido/blob/main/server/src/question_loader.py"
        QuestionsStore["Questions JSON Store"]:::persistence
        click QuestionsStore "https://github.com/miltchola/quiz-distribuido/tree/main/server/src/questions/"
    end
    click QuizServerEntry "https://github.com/miltchola/quiz-distribuido/blob/main/server/src/main.py"
    QuizServerEntry["QuizServer Entrypoint"]:::network

    %% Flows
    QuizClient -->|"connect"| TCPSocket
    TCPSocket -->|"connect"| ConnectionListener
    ConnectionListener -->|"accepts connection"| GameManager
    GameManager -->|"load questions"| QuestionLoader
    QuestionLoader -->|"reads JSON"| QuestionsStore
    GameManager -->|"question"| TCPSocket
    TCPSocket -->|"question"| QuizClient
    QuizClient -->|"answer"| TCPSocket
    TCPSocket -->|"answer"| GameManager
    GameManager -->|"feedback"| TCPSocket
    TCPSocket -->|"feedback"| QuizClient
    GameManager -->|"result"| TCPSocket
    TCPSocket -->|"result"| QuizClient

    %% Protocol association
    Protocol -.-> QuizClient
    Protocol -.-> ConnectionListener
    Protocol -.-> GameManager

    %% Entrypoint link
    ConnectionListener --> QuizServerEntry

    %% Styles
    classDef client fill:#e0f7fa,stroke:#006064,color:#000
    classDef network fill:#bbdefb,stroke:#0d47a1,color:#000
    classDef logic fill:#c8e6c9,stroke:#1b5e20,color:#000
    classDef persistence fill:#ffe0b2,stroke:#e65100,color:#000
    classDef shared fill:#eceff1,stroke:#455a64,color:#000
```
