Exavatar

Este documento detalha a arquitetura, o design de domínio e a implementação técnica do Exavatar, um motor de renderização e API de geração dinâmica de avatares. Esta solução aborda um ponto de atrito recorrente no desenvolvimento de aplicações web e móveis: o gerenciamento de imagens de perfil padrão ou placeholders quando o usuário final não fornece uma.

Utilidade e Fluxo de Trabalho

O problema central que este projeto resolve é a ausência de uma identidade visual temporária nas interfaces de usuário, o que normalmente exige que cada equipe de desenvolvimento implemente lógica redundante para gerar iniciais ou carregar imagens condicionalmente no lado do cliente.

O Exavatar transfere essa responsabilidade inteiramente para o servidor. A ferramenta atua como uma API REST que, por meio de parâmetros de URL estruturados, retorna um avatar de forma instantânea. Ela pode servir um recurso estático de uma coleção predefinida (por exemplo, animais ou personagens em formato WEBP/PNG) ou gerar dinamicamente um SVG com as iniciais do usuário sobre um fundo de cor sólida.

O fluxo principal da aplicação funciona da seguinte forma:

1. Recepção da Requisição: Um cliente faz uma requisição HTTP GET à API com parâmetros específicos (set, id, size, format, color, text).
2. Avaliação do Domínio: O núcleo da aplicação interpreta os parâmetros da URL para instanciar a entidade principal (Avatar). Se o parâmetro text for fornecido, a aplicação determina que deve compilar e retornar um SVG gerado dinamicamente. Caso contrário, valida os atributos de tamanho, coleção e formato para construir um caminho de arquivo válido.
3. Resolução do Repositório: Dependendo do ambiente de execução (Desenvolvimento vs. Produção), a camada de aplicação delega o carregamento físico da imagem ao adaptador de infraestrutura correspondente (local ou baseado em rede).
4. Resposta: O servidor retorna o binário da imagem ou a string SVG com os cabeçalhos HTTP corretos e o cache configurado, minimizando a carga computacional em requisições subsequentes.

---

Análise Aprofundada: Arquitetura e Modelagem de Dados

O design do código-fonte (localizado principalmente em src/core/) é uma implementação estrita de Domain-Driven Design (DDD) estruturada sob o padrão de Arquitetura Hexagonal (Portas e Adaptadores). Essa decisão técnica não é casual; foi adotada para isolar completamente a lógica de negócio e as regras de geração da camada de apresentação (Astro) e da camada de infraestrutura (rede/sistema de arquivos).

Arquitetura Geral

A separação de responsabilidades garante que o núcleo (domain) não tenha dependências externas, tornando o código inerentemente testável e escalável.

flowchart TD
    subgraph Presentation ["Apresentação (Astro / API Routes)"]
        API["Rota /api/avatar"]
    end

    subgraph ApplicationLayer ["Camada de Aplicação"]
        AS["AvatarService"]
    end

    subgraph DomainLayer ["Camada de Domínio (Núcleo)"]
        A["Avatar : Entidade"]
        VO1["AvatarSize : Value Object"]
        VO2["AvatarColor : Value Object"]
        VO3["AvatarId : Value Object"]
        VO4["AvatarSet : Value Object"]
        VO5["AvatarText : Value Object"]
        Repo["AvatarRepository : Porta"]

        A --> VO1
        A --> VO2
        A --> VO3
        A --> VO4
        A --> VO5
    end

    subgraph InfrastructureLayer ["Camada de Infraestrutura (Adaptadores)"]
        LRepo["LocalAvatarRepository"]
        GRepo["GitHubAvatarRepository"]
    end

    API --> AS
    AS --> Repo
    AS --> A
    LRepo -.-> Repo
    GRepo -.-> Repo

Modelagem de Dados e Lógica de Negócio

A lógica de negócio reside nos Value Objects e na entidade Aggregate Root (Avatar). Eles garantem que a aplicação nunca processe um estado inválido.

• Entidade Avatar: Orquestra a validação e a transformação. Expõe o método needBuild(), que determina o fluxo de execução (leitura de um arquivo estático vs. geração de um SVG) avaliando se o Value Object AvatarText contém um valor válido.
• Value Objects:
  • AvatarSize: Valida os limites e resoluções permitidos (por exemplo, restringindo entre 16px e 512px).
  • AvatarColor: Normaliza valores hexadecimais e calcula lógica secundária (como o contraste automático do texto do SVG com base na luminância da cor de fundo).
  • AvatarId, AvatarSet e AvatarFormat: Garantem que o identificador solicitado pertença a uma coleção válida e que o formato de saída seja suportado (webp, png, svg).

classDiagram
    class Avatar {
        +AvatarSet set
        +AvatarId id
        +AvatarSize size
        +AvatarFormat format
        +AvatarColor color
        +AvatarText text
        +String filepath
        +String filename
        +fromUrl(URL url) Avatar$
        +needBuild() boolean
    }
    class AvatarService {
        -AvatarRepository repository
        +generate(URL url) Promise<AvatarResult>
    }
    class AvatarRepository {
        <<interface>>
        +load(Avatar avatar) Promise<AvatarResult>
    }

    AvatarService --> AvatarRepository : Usa
    AvatarService ..> Avatar : Constrói

O serviço orquestrador, AvatarService, aplica injeção de dependência via construtor. Em tempo de execução, o sistema injeta GitHubAvatarRepository para obter arquivos estáticos do repositório de produção, ou LocalAvatarRepository para ler do disco local durante o desenvolvimento.

Stack Tecnológico

O conjunto de ferramentas foi selecionado com rigor, priorizando desempenho e controle de tipos.

Tecnologia	Papel na Arquitetura
Astro	Framework de apresentação e Server-Side Rendering (SSR). Gerencia o roteamento da API e entrega respostas rápidas por meio da Edge Network sem injetar JavaScript no cliente.
TypeScript	Linguagem de programação principal. Fundamental para a modelagem na camada de Domínio, garantindo o cumprimento rigoroso das interfaces entre portas e adaptadores.
Vitest	Ambiente de testes unitários. Permite testar a camada de domínio e o AvatarService em completo isolamento, injetando repositórios simulados (mocks).
BiomeJS	Única ferramenta de análise estática (linter) e formatação. Configurada para usar indentação com tabulações e aspas simples, substituindo completamente o Prettier e o ESLint para maior velocidade de execução.
Vercel	Infraestrutura de implantação. Utiliza Serverless/Edge Functions diretamente via @astrojs/vercel para o processamento e a entrega global por CDN das imagens geradas.

---

A integração rigorosa dos princípios de DDD, da tipagem estática avançada e de uma arquitetura hexagonal pura em um ambiente JavaScript moderno resulta em um sistema sem acoplamento entre seu motor de renderização e sua infraestrutura de distribuição de arquivos. Essa abstração permite escalar, trocar de plataforma de hospedagem ou adicionar novos formatos de geração algorítmica sem exigir alterações na lógica de domínio.