🌌 HOLOCRON ANALYTICS

"Onde a Força dos Dados se Encontra com a Sabedoria da Galáxia"

📑 Índice

• 📜 Visão Geral
• 📂 Estrutura do Projeto
• 🏗️ Arquitetura e Engenharia de Performance
• 🛠️ Bastidores da Engenharia (Deep Dive)
• 🗺️ Navegação e Funcionalidades
• 🔗 Integração & Protocolos de Dados
• 📚 Documentação Técnica (Deep Dive)
  • 🤖 Engenharia de IA & NLP
  • 🎮 Mecânicas de Gamificação
  • 🚀 Guia de Deploy em Produção
  • 🎨 UX & Frontend Architecture
  • 📐 Quality Assurance & Data Architecture
• 🛡️ Infraestrutura & Segurança (DevSecOps)
• 🔌 API Reference (Endpoints)
• 🎨 Design System
• 📋 Variáveis de Ambiente
• 💻 Stack Tecnológico Detalhado
• 🚀 Como Executar
• 👨‍💻 Desenvolvedor

📜 Visão Geral

O Holocron Analytics é uma plataforma imersiva e gamificada desenvolvida para explorar o universo de Star Wars. Muito além de uma simples wiki, este projeto transforma a consulta de dados da API pública (SWAPI) em uma experiência de "Arquivista Jedi", utilizando Inteligência Artificial (OpenAI GPT-4o) para enriquecer dados, gerar quizzes dinâmicos e simular interações com o Mestre Yoda.

Principais Funcionalidades

• 🔍 Holocron Digital: Consulta avançada de Personagens, Filmes, Naves, Planetas, Espécies e Veículos.
• 🤖 Mestre Yoda AI: Um chatbot integrado alimentado por LLM que responde perguntas sobre a galáxia com a personalidade do icônico Mestre Jedi, utilizando dados cacheados para respostas ultra-rápidas.
• ⚔️ Gamificação & Jedi Trials: Sistema de progressão onde o usuário sobe de rankings (Padawan -> Mestre) ao completar desafios e quizzes.
• 📊 Relatórios Visuais: Gráficos detalhados sobre a distribuição de espécies, veículos por filme e estatísticas da galáxia.
• 🚀 Performance Extrema: Estratégias avançadas de caching e carregamento em background para uma navegação instantânea.
• 📱 Design Responsivo: Interface totalmente adaptada para desktop, tablet e mobile com UX de alto nível.

📂 Estrutura do Projeto

Star-Wars-App/
├── backend/                          # API FastAPI (Python)
│   ├── src/app/
│   │   ├── application/              # Camada de Aplicação (Use Cases)
│   │   │   └── services/             # Services de negócio
│   │   │       ├── chat_service.py          # Motor de chat com IA
│   │   │       ├── gamification_service.py  # Sistema de XP e conquistas
│   │   │       ├── quiz_service.py          # Geração de quizzes com IA
│   │   │       └── rag_search.py            # Motor de busca híbrido (RAG)
│   │   ├── domain/                   # Camada de Domínio (DDD)
│   │   │   ├── entities/             # Entidades de negócio
│   │   │   ├── enums/                # Enumerações (JediRank, etc.)
│   │   │   ├── exceptions/           # Exceções customizadas
│   │   │   ├── repositories/         # Interfaces de repositório
│   │   │   └── schemas/              # Schemas Pydantic (DTOs)
│   │   ├── infrastructure/           # Camada de Infraestrutura
│   │   │   ├── cache/                # Sistema de cache em memória
│   │   │   ├── config/               # Configurações (Settings)
│   │   │   ├── db/                   # SQLAlchemy models e conexão
│   │   │   ├── external/             # Integrações externas
│   │   │   │   ├── openai/           # Cliente OpenAI (GPT-4o)
│   │   │   │   └── swapi/            # Cliente SWAPI
│   │   │   ├── security/             # JWT, Auth handlers
│   │   │   └── etag_middleware.py    # Middleware de cache HTTP
│   │   └── interfaces/               # Camada de Interface
│   │       └── api/v1/
│   │           ├── routers/          # Endpoints da API
│   │           │   ├── auth.py              # Autenticação Google OAuth
│   │           │   ├── characters.py        # CRUD Personagens
│   │           │   ├── chat.py              # Chat com IA
│   │           │   ├── films.py             # CRUD Filmes
│   │           │   ├── gamification.py      # XP, Ranking, Achievements
│   │           │   ├── health.py            # Health check
│   │           │   ├── image_fallbacks.py   # Gestão de imagens
│   │           │   ├── metadata.py          # Metadados para filtros
│   │           │   ├── planets.py           # CRUD Planetas
│   │           │   ├── species.py           # CRUD Espécies
│   │           │   ├── starships.py         # CRUD Naves
│   │           │   └── vehicles.py          # CRUD Veículos
│   │           └── dependencies/     # Injeção de dependências
│   ├── alembic/                      # Migrações de banco
│   │   └── versions/                 # Scripts de migração
│   ├── tests/                        # Testes unitários (Pytest)
│   ├── Dockerfile.cloud-run          # Dockerfile para produção
│   ├── Dockerfile.dev                # Dockerfile para desenvolvimento
│   └── pyproject.toml                # Dependências Python (Poetry)
│
├── frontend/                         # SPA React (TypeScript)
│   ├── src/
│   │   ├── App/                      # Componente raiz e navegação
│   │   ├── features/                 # Módulos por domínio (Feature-based)
│   │   │   ├── auth/                 # Autenticação Google
│   │   │   │   ├── components/       # UserMenu, LoginButton
│   │   │   │   ├── context/          # AuthProvider, AuthContext
│   │   │   │   ├── pages/            # LoginPage, AuthLoadingPage
│   │   │   │   └── services/         # authService (API calls)
│   │   │   ├── characters/           # Módulo Personagens
│   │   │   │   ├── components/       # CharacterCard, CharacterModal
│   │   │   │   ├── hooks/            # useCharacters, useCharacterDetails
│   │   │   │   ├── pages/            # CharactersPage
│   │   │   │   └── services/         # charactersService
│   │   │   ├── chat/                 # Módulo Chat com IA
│   │   │   │   ├── components/       # YodaChatBubble, ChatModal
│   │   │   │   ├── context/          # ChatProvider
│   │   │   │   └── hooks/            # useChat, useChatHistory
│   │   │   ├── dashboard/            # Dashboard principal
│   │   │   ├── films/                # Módulo Filmes
│   │   │   ├── gamification/         # Módulo Gamificação
│   │   │   │   ├── components/       # QuizModal, AchievementCard
│   │   │   │   ├── hooks/            # useGamification, useQuiz
│   │   │   │   └── pages/            # GamificationPage
│   │   │   ├── planets/              # Módulo Planetas
│   │   │   ├── reports/              # Módulo Relatórios
│   │   │   │   ├── components/       # Charts, LeaderboardTable
│   │   │   │   └── pages/            # ReportsPage
│   │   │   ├── species/              # Módulo Espécies
│   │   │   ├── starships/            # Módulo Naves
│   │   │   └── vehicles/             # Módulo Veículos
│   │   └── shared/                   # Código compartilhado
│   │       ├── components/           # Componentes reutilizáveis
│   │       │   ├── CustomSelect/     # Select customizado Star Wars
│   │       │   ├── FilmFilter/       # Filtro global por filme
│   │       │   ├── PageLayout/       # Layout base das páginas
│   │       │   ├── Pagination/       # Paginação responsiva
│   │       │   ├── ScrollToTop/      # Botão voltar ao topo
│   │       │   └── StarfieldEvents/  # Background animado
│   │       ├── hooks/                # Hooks compartilhados
│   │       │   ├── useFilmOptions.ts        # Options de filmes
│   │       │   ├── useMetadataOptions.ts    # Metadata para filtros
│   │       │   └── usePrefetchAllData.ts    # Prefetch em 6 fases
│   │       ├── services/             # Services compartilhados
│   │       │   ├── api.ts                   # Cliente HTTP base
│   │       │   └── metadata.service.ts      # Service de metadados
│   │       ├── stores/               # Zustand stores
│   │       └── styles/               # Estilos globais
│   │           └── global.css        # CSS Variables, Starfield
│   ├── api/                          # Vercel Serverless Functions
│   ├── index.html                    # Entry point HTML
│   ├── vite.config.ts                # Configuração Vite
│   └── package.json                  # Dependências Node.js
│
├── regras-desenvolvimento-python-react/  # Documentação de padrões
│   ├── regras-backend.md             # Padrões Python/FastAPI
│   ├── regras-frontend.md            # Padrões React/TypeScript
│   └── regras-testes.md              # Padrões de testes
│
├── docker-compose.dev.yml            # Compose para desenvolvimento
├── deploy-starwars.ps1               # Script de deploy GCP
└── README.md                         # Esta documentação

🏗️ Arquitetura e Engenharia de Performance

A solução foi projetada com foco obsessivo em performance e fluidez (UX), utilizando uma estratégia de carregamento inteligente e cache multinível.

%%{title: "Estratégia de Performance e Cache"}%%
flowchart TD
    Init["🚀 Inicialização do App"] --> FastLoad["🔥 Carregamento Crítico"]
    FastLoad --> Render["🖥️ Renderização Imediata (LCP Otimizado)"]
    
    Render --> Background["⏳ Carregamento em Background"]
    Background --> FetchAll["📡 Fetch Massivo da SWAPI"]
    FetchAll --> Process["⚙️ Processamento & Enriquecimento"]
    Process --> Cache["💾 Cache Local (Memory)"]
    
    subgraph UX_Fluidity ["Navegação Fluida"]
        UserAction["🖱️ Navegação do Usuário"]
        UserAction -- "Dados já em Cache" --> InstantServe["⚡ Exibição Instantânea"]
        UserAction -- "Chat/Quiz" --> ContextAware["🧠 Contexto Pré-carregado"]
    end
    
    Cache -.-> UX_Fluidity

🧠 Pipeline de Inteligência Artificial

A integração com a IA não é apenas um "wrapper". Ela atua ativamente para cobrir lacunas de dados e gerar conteúdo.

%%{title: "Pipeline de Enriquecimento de Dados com IA"}%%
sequenceDiagram
    participant C as Client
    participant B as Backend
    participant DB as Banco de Dados
    participant SW as SWAPI
    participant AI as Vertex AI (Gemini)

    C->>B: GET /characters/1 (Luke Skywalker)
    B->>DB: Busca Cache Local
    
    alt Dados Incompletos ou Inexistentes
        B->>SW: Fetch Dados Básicos
        SW-->>B: JSON Bruto (SWAPI)
        B->>AI: Prompt: "Gere stats de RPG para Luke"
        AI-->>B: JSON Enriquecido (Força: 85, Agilidade: 80...)
        B->>DB: Salva/Atualiza Registro
    end
    
    B-->>C: Retorna Personagem Completo + Stats

🛠️ Bastidores da Engenharia (Deep Dive)

O que diferencia o Holocron Analytics é a atenção aos detalhes técnicos "invisíveis" que tornam a experiência mágica.

1. 🔍 Otimização de Busca (NLP & RAG)

O sistema de busca (rag_search.py) implementa um motor de Retrieval-Augmented Generation que entende português nativo.

• Fuzzy Search Híbrida: Utiliza rapidfuzz (Levenshtein Distance) para corrigir erros de digitação ("Anakin Skywaler" -> Encontra "Anakin Skywalker").
• Stemming PT-BR: Algoritmo customizado que remove sufixos (-inho, -mente, -ão) para entender a intenção da busca.
• Detecção de Entidades: Heurísticas inteligentes diferenciam quando o usuário busca um droide ("R2") vs. um termo genérico, evitando falsos positivos.
• Sinônimos: Mapeia automaticamente termos como "sabre de luz" ↔ "lightsaber" ou "robô" ↔ "droid".

2. 🧙 Engenharia de Persona (Prompting)

O Mestre Yoda AI não é apenas um chatbot padrão.

• Contexto Dinâmico: O sistema injeta snippets de dados oficiais da SWAPI no contexto do modelo para garantir que as respostas sejam factuais (Grounding), reduzindo alucinações.
• Inversão Sintática: O prompt do sistema instrui a IA a mimetizar a gramática única do Yoda (Objeto-Sujeito-Verbo).
• Múltiplas Personas: A arquitetura suporta troca de personas, permitindo conversar também com uma versão "Darth Vader", que responde com hostilidade e emojis proibidos.

3. ✨ Frontend Cinematográfico

A interface foi construída para imersão total:

• Starfield Dinâmico: O fundo de estrelas (StarfieldEvents.tsx) não é um vídeo em loop. É um sistema de partículas gerado proceduralmente que simula "tráfego espacial", com meteoros variando em velocidade, ângulo e profundidade.
• Acessibilidade: O sistema detecta a preferência prefers-reduced-motion do sistema operacional e desativa automaticamente animações pesadas para usuários sensíveis à cinética.

🗺️ Navegação e Funcionalidades

1. 🔍 Holocron (Exploração de Dados)

Páginas dedicadas para cada entidade do universo Star Wars, com cards ricos e interativos.

• Páginas: Personagens, Filmes, Naves, Planetas, Espécies, Veículos.
• Filtros Avançados:
  • Filtragem por Nome, Gênero, Clima (Planetas), Classe (Naves), e muito mais.
  • Busca fuzzy (aproximada) para encontrar termos mesmo com erros de digitação.
  • Ordenação dinâmica e paginação instantânea (client-side pagination graças ao pré-carregamento).

2. 📊 Relatórios e Analytics

Localizado na pasta reports, esta seção oferece insights visuais através de gráficos interativos.

• Distribuição de Espécies: Gráficos de pizza/barras mostrando a diversidade da galáxia.
• Comparativo de Naves: Gráficos de dispersão comparando velocidade vs. custo.
• Cronologia: Linha do tempo visual dos filmes e eventos.

3. ⚔️ Gamificação Completa

O sistema mantém os usuários engajados através de um sistema de níveis e recompensas.

• Jedi Trials: Quizzes gerados por IA que testam conhecimento.
• Barra de XP: Ganhe experiência explorando o sistema, completando quizzes e descobrindo "easter eggs".
• Rankings: Comece como Youngling, torne-se Padawan, Cavaleiro e, finalmente, Mestre Jedi.
• Conquistas: Medalhas desbloqueáveis (ex: "Visitou todos os planetas", "Acertou 10 perguntas seguidas").

4. ⚡ Estratégia de Carregamento em Fases (6-Phases Prefetch)

Para garantir uma experiência "instantânea", o frontend (usePrefetchAllData.ts) implementa um pipeline de hydration em 6 estágios, que roda silenciosamente em background:

1. Fase 1 (Crítica): Dashboard (LCP). Carrega dados para a Home.
2. Fase 2 (Navegação): Primeiras 3 páginas de TODAS as listagens (Personagens, Naves, etc).
3. Fase 3 (Conteúdo Rico): Detalhes completos de todos os filmes.
4. Fase 4 (Big Data): Carrega datasets massivos (100+ itens) para gerar os gráficos da página de Relatórios.
5. Fase 5 (Social): Perfil do usuário, conquistas, ranking e desafios diários.
6. Fase 6 (Bulk Quiz): Baixa centenas de perguntas potenciais para que o Jedi Trials funcione offline/sem delay.

Tudo isso ocorre sem bloquear a thread principal, utilizando setTimeout e gerenciamento de prioridades do React Query.

5. 🛡️ Middleware de Cache Inteligente

O backend não confia apenas no browser. Implementamos um ETag Middleware Global (etag_middleware.py) que:

• Intercepta todas as respostas JSON.
• Gera um hash SHA-256 do conteúdo.
• Compara com o header If-None-Match da requisição.
• Retorna 304 Not Modified (0 bytes de corpo) se os dados não mudaram, economizando banda e processamento do cliente.

6. 🖼️ Image Lookup & Fallback Strategy

A SWAPI oficial não entrega imagens. O ImageLookupService implementa uma estratégia de resolução em camadas:

1. Databank Index: Tenta cruzar o nome do recurso com um índice de imagens extraído do Databank oficial de Star Wars.
2. Legacy Fallback: Se falhar, busca em uma tabela local (image_fallbacks) mapeada manualmente para itens obscuros.
3. Conservative Matching: Utiliza algoritmos de normalização de strings (casefold + strip) para garantir que "X-Wing" encontre "x-wing fighter", mas retorna None se não houver certeza absoluta (evitando imagens erradas).

7. 📑 Paginação Abstrata (SWAPI Slicing)

A SWAPI força paginação de 10 itens. O frontend precisa de grids de 12, 8 ou 100 itens. O módulo swapi_pagination.py resolve isso com Virtual Slicing:

• Calcula matematicamente quais páginas da SWAPI (ex: pág 3 e 4) contêm os itens do slice desejado (ex: itens 25 a 36).
• Busca apenas as páginas necessárias em paralelo (asyncio.gather).
• Combina os resultados e corta o array exato para o cliente.
• Resultado: O frontend pode pedir pageSize=100 e o backend orquestra 10 chamadas paralelas à SWAPI de forma transparente.

8. 🎮 Gamification Engine (Jedi Trials)

O sistema de engajamento (gamification_service.py) não é apenas um contador de pontos.

• Behavioral Achievements: Conquistas como "Amigo de Yoda" ou "Lacaio de Vader" são desbloqueadas analisando o histórico de interações com personas específicas (chat_stats_by_persona).
• Live XP & Ranks: O cálculo de nível é instantâneo, utilizando uma curva de progressão baseada no XP acumulado (Youngling $\to$ Padawan $\to$ Knight $\to$ Master).
• Leaderboard Aggregation: Consultas SQL otimizadas agregam estatísticas complexas em tempo real, calculando precisão (% de acertos) e melhores sessões de quiz para o ranking global.

🔗 Integração & Protocolos de Dados (End-to-End)

A arquitetura de comunicação com a SWAPI foi desenhada para ser resiliente e invisível ao usuário final. Abaixo, detalho o fluxo completo de uma requisição.

1. Protocolo de Cliente (SWAPIClient)

O SWAPIClient (src/app/infrastructure/external/swapi/client.py) atua como um gateway inteligente:

• Http Keep-Alive: Utiliza httpx.AsyncClient para manter conexões persistentes, reduzindo o overhead de handshake TCP/TLS em múltiplas requisições.
• Transparent Pagination: O método _paginate_all abstrai a lógica de cursores next da API, iterando automaticamente até consumir todos os dados quando necessário (ex: para relatórios).
• Url Normalization: O cliente normaliza URLs e IDs automaticamente, garantindo que https://swapi.dev/api/people/1/ e https://swapi.dev/api/people/1 sejam tratados como o mesmo recurso no cache.

2. Fluxo de Dados (Sequence Diagram)

O diagrama abaixo ilustra o caminho de uma requisição simples (ex: "Listar Naves") e como o sistema decide entre Cache, API Externa e Image Lookup.

sequenceDiagram
    participant UI as Frontend (React Query)
    participant API as FastAPI Backend
    participant Cache as Memory Cache (TTL)
    participant SWAPI as SWAPI.dev
    participant DB as PostgreSQL (Images Setup)

    UI->>API: GET /starships?page=1&pageSize=12
    API->>Cache: GET swapi:starships:page:1
    
    alt Cache Miss (Primeiro Acesso)
        API->>SWAPI: GET /starships/?page=1 & page=2 (Parallel)
        SWAPI-->>API: JSON Raw Data
        
        API->>DB: Resolve Image URLs (Virtual Join)
        DB-->>API: URLs das Naves
        
        API->>API: Normaliza Dados (snake_case, números)
        API->>Cache: SET swapi:starships:page:1 (TTL 1h)
        API-->>UI: JSON Otimizado + Imagens
    else Cache Hit
        Cache-->>API: Dados Prontos
        API-->>UI: Resposta Instantânea (<10ms)
    end

3. Tratamento e Normalização de Dados

A SWAPI retorna dados "sujos" para os padrões modernos (strings para números, snake_case misto). O StarWarsApp implementa uma camada de Data Sanitization:

• Number Parsing: O utilitário parse_swapi_number converte strings complexas como "unknown", "n/a", ou ranges "30-165" em tipos numéricos seguros (Optional[float]) para permitir ordenação e gráficos corretos.
• Date Standardization: Todas as datas são convertidas para ISO-8601 estrito.
• Cross-Reference Resolving: URLs de relacionamento (ex: pilots: [...]) são mantidas como referência mas preparadas para lazy loading no frontend.

4. 🔐 Protocolo de Autenticação Segura (JWT + Cookie)

Implementamos o padrão Silent Refresh para segurança máxima:

• Access Token: Curta duração (15min), armazenado em memória (JavaScript), usado como Bearer Token.
• Refresh Token: Longa duração (7 dias), armazenado em Cookie HttpOnly (Secure, SameSite), inacessível via JS.
• Token Rotation: A cada refresh, o token anterior é invalidado e um novo é emitido, prevenindo replay attacks.

sequenceDiagram
    participant U as User
    participant F as Frontend
    participant B as Backend
    participant D as Database
    
    U->>F: Login com Google
    F->>B: Envia Credencial Google
    B->>D: Verifica/Cria User
    B-->>F: Retorna Access Token + User Info
    B-->>U: Set-Cookie: refresh_token (HttpOnly)
    
    Note over F,B: Navegação Segura
    
    F->>B: GET /api/v1/characters (Bearer Access)
    B-->>F: 200 OK
    
    Note over F,B: Access Token Expira
    
    F->>B: GET /api/v1/characters
    B-->>F: 401 Unauthorized
    F->>B: POST /auth/refresh (Cookie Automático)
    B->>D: Valida Refresh Token
    B-->>F: Novo Access Token
    B-->>U: Set-Cookie: Novo refresh_token
    F->>B: Retry Requisição Original

5. 🤖 Motor de Chat Contextual (ChatService)

O chat_service.py é o cérebro da aplicação, orquestrando mais de 2.000 linhas de lógica condicional e IA.

• Intent Routing: Antes de chamar a LLM, o sistema analisa a intenção com heurísticas regex. Ex: "Quem é Luke?" consulta diretamente o banco local/SWAPI, economizando tokens e latência.
• RAG Pipeline:
  1. Extract Entities: Identifica "Luke", "Tatooine" na frase.
  2. Hybrid Search: Busca vetorial + palavras-chave no banco de conhecimento.
  3. Context Injection: Injeta snippets JSON (ex: stats de força) no system prompt.
  4. Persona Tuning: Ajusta a resposta para o estilo "Yoda" (inversão sintática) ou "Vader".

📚 Documentação Técnica (Deep Dive)

Para desenvolvedores que desejam entender os detalhes internos, documentamos todos os subsistemas críticos diretamente aqui:

flowchart TD
    UserInput["🗣️ Mensagem do Usuário"] --> PreProcess["🔧 Pré-processamento"]
    PreProcess --> Routing{⚡ Roteamento de Intenção}
    
    Routing -- "Regex/Padrão Fixo" --> DirectReply["📝 Resposta Direta (Sem LLM)"]
    Routing -- "Pergunta Complexa" --> RAG["🔍 RAG Search (Context Recovery)"]
    
    RAG -- "Dados Encontrados" --> ContextInj["💉 Injeção de Contexto (JSON)"]
    ContextInj --> PromptEng["🎭 Engenharia de Persona"]
    PromptEng --> LLM["🤖 Invocação da IA"]
    
    LLM --> Response["💬 Resposta Final"]
    DirectReply --> Response

DADOS SWAPI (referência factual):
{
  "name": "Luke Skywalker",
  "height": "172",
  "mass": "77",
  "hair_color": "blond",
  "skin_color": "fair",
  "eye_color": "blue",
  "birth_year": "19BBY",
  "gender": "male"
}

Regras:
- Para atributos que estejam nos dados, use os valores acima como fonte de verdade.
- Não invente números se não estiverem aqui.

# Pseudocódigo da regra
if yoda_messages >= 5: unlock("amigo_yoda")
if vader_messages >= 5: unlock("lacaio_vader")

# Exemplo: Criando o segredo do JWT
printf "minha-chave-super-secreta" | gcloud secrets create holocron-jwt-secret-key --data-file=-

# Exemplo: Criando o segredo do Banco
printf "senha-do-banco" | gcloud secrets create holocron-db-password --data-file=-

.\deploy-starwars.ps1

.\deploy-starwars.ps1 -Region "us-central1"

gcloud run services logs read star-wars-backend

🛡️ Infraestrutura & Segurança (DevSecOps)

A segurança não é um "add-on", mas parte do design da infraestrutura cloud-native.

1. 🔑 Gestão de Segredos (Secrets Management)

Adotamos uma estratégia de Zero Hardcoded Secrets.

• Frontend (Vercel): As chaves públicas (Google Client ID) e URLs de API são injetadas em tempo de build via variáveis de ambiente da Vercel. Nenhuma chave privada toca o bundle do cliente.
• Backend (Google Cloud Run): Segredos críticos (DB Password, JWT Secret, OpenAI Key) são gerenciados pelo GCP Secret Manager. Eles são montados no container como variáveis de ambiente em tempo de execução, garantindo que nem mesmo o Dockerfile tenha acesso a eles.

2. 🐳 Pipeline de Conteinerização Segura

O Dockerfile.cloud-run segue as melhores práticas de hardening:

• Minimal Base Image: Baseado em python:3.12-slim para reduzir drasticamente a superfície de ataque (menos binários vulneráveis).
• Stateless by Design: O container não retém dados. Uploads e persistência são delegados para serviços externos (Storage/PostgreSQL).
• Auto-Migrations: O comando de entrypoint executa alembic upgrade head a cada deploy, garantindo que o esquema do banco esteja sempre sincronizado com o código da aplicação (Infrastructure as Code).

3. 💾 Persistência e Resiliência

Embora a aplicação seja altamente dependente de cache, o PostgreSQL serve como fonte da verdade para dados críticos:

• Perfis de Usuário: Dados sensíveis e progresso de gamificação.
• Fallback de Imagens: Nossa tabela image_fallbacks atua como um sistema de failover. Se o CDN de imagens externo falhar, o sistema reverte automaticamente para ativos curados armazenados no banco.

graph TD
    subgraph "Public Zone (Vercel)"
        Frontend[React SPA]
    end
    
    subgraph "Private Zone (Google Cloud Platform)"
        LB[Load Balancer HTTPS]
        
        subgraph "Cloud Run (Auto-Scaling)"
            API[FastAPI Container]
        end
        
        Secret[GCP Secret Manager]
        DB[(PostgreSQL)]
        Vertex[Vertex AI]
    end
    
    Frontend -- "Bearer JWT (TLS 1.3)" --> LB
    LB --> API
    
    API -- "Env Vars Injection" --> Secret
    API -- "SQLAlchemy (Connection Pool)" --> DB
    API -- "IAM Credentials" --> Vertex
    
    style Secret fill:#f9f,stroke:#333
    style DB fill:#ccf,stroke:#333

9. 🛡️ Compliance & Security Standards (RBAC & OWASP)

O projeto foi auditado seguindo princípios rigorosos de segurança de software, alinhados com o OWASP Top 10 e regras corporativas de compliance.

9.1 Acesso e Identidade (RBAC & Invoker)

• Cloud Run Invoker: O backend não é público. Ele opera em modo authenticated-only, aceitando apenas requisições com um token OIDC válido assinado pelo Google (via Service Account da Vercel). Ninguém consegue acessar a API diretamente sem passar pelo frontend.

• RBAC (Role-Based Access Control): Internamente, endpoints administrativos validam o token JWT. Apenas usuários autenticados (require_authenticated_user_id) podem persistir dados ou gerar relatórios complexos.

9.2 Prevenção de Vulnerabilidades (OWASP)

9.3 Cloud Run Private Access Diagram

Este grafo mostra como o acesso ao backend é blindado.

%%{title: "Cloud Run Private Access & API Shielding"}%%
flowchart LR
    subgraph External_World ["External World"]
        User[Usuário]
        Hacker[Atacante]
    end
    
    subgraph Security_Perimeter ["Security Perimeter (Google Auth)"]
        Vercel["Vercel Frontend"]
    end
    
    subgraph Private_Zone ["Private Zone (Secure Backend)"]
        CloudRun["Cloud Run Backend"]
        DB[("PostgreSQL")]
        Secrets["Secret Manager"]
    end
    
    subgraph Shielded_APIs ["External APIs (Shielded)"]
        SWAPI["SWAPI (Data)"]
        AI["OpenAI / Vertex AI"]
    end
    
    %% Fluxo do Usuário
    User -- HTTPS --> Vercel
    Hacker -. "Direct Access (403 Forbidden)" .-> CloudRun
    
    %% Autenticação Service-to-Service
    Vercel -- "OIDC ID Token (Auth)" --> CloudRun
    
    %% Backend Acessando Recursos
    CloudRun -- "Internal Traffic" --> DB
    CloudRun -- "Load API Keys" --> Secrets
    
    %% Shielding: O Backend protege as chaves e limita o rate-limit
    CloudRun -- "Proxied Request" --> SWAPI
    CloudRun -- "Secure Context" --> AI
    
    %% Styling
    style Vercel fill:#000,color:#fff
    style CloudRun fill:#4285F4,color:#fff
    style Hacker stroke:red,stroke-width:2px,stroke-dasharray: 5 5
    style Secrets fill:#FFEB3B,color:#000

🔌 API Reference (Endpoints)

A API REST segue os padrões OpenAPI 3.0. Documentação interativa disponível em /docs (Swagger UI).

🔐 Autenticação (/api/v1/auth)

👤 Personagens (/api/v1/characters)

Query Params: page, pageSize, search, gender, homeworld, species, film, sort

🎬 Filmes (/api/v1/films)

🚀 Naves (/api/v1/starships)

Query Params: page, pageSize, search, starship_class, manufacturer, film, sort

🌍 Planetas (/api/v1/planets)

Query Params: page, pageSize, search, climate, terrain, film, sort

👽 Espécies (/api/v1/species)

Query Params: page, pageSize, search, classification, designation, language, film, sort

🚗 Veículos (/api/v1/vehicles)

Query Params: page, pageSize, search, vehicle_class, manufacturer, film, sort

🤖 Chat com IA (/api/v1/chat)

Body (POST):

{
  "message": "Quem é Luke Skywalker?",
  "persona": "yoda"  // ou "vader"
}

🎮 Gamificação (/api/v1/gamification)

📊 Metadados (/api/v1/metadata)

🖼️ Imagens (/api/v1/image-fallbacks)

❤️ Health Check (/api/v1/health)

🎨 Design System

A interface do Holocron Analytics foi projetada para proporcionar uma experiência imersiva no universo Star Wars.

🎨 Paleta de Cores

✨ Efeitos Visuais

• Glassmorphism: Cards com backdrop-filter: blur(12px) e bordas translúcidas.
• Neon Glow: Sombras coloridas (box-shadow) para elementos interativos.
• Starfield Dinâmico: Background animado com partículas em CSS/JS.
• Hover Transitions: Efeitos suaves com transform e opacity (0.2s ease).

🧩 Componentes Reutilizáveis

🪝 Hooks Customizados

📋 Variáveis de Ambiente

Backend (.env ou GCP Secret Manager)

# 🔌 Banco de Dados
DATABASE_URL=postgresql://user:password@host:5432/dbname

# 🔐 Autenticação
JWT_SECRET_KEY=sua-chave-secreta-256-bits
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=15

# 🌐 Google OAuth
GOOGLE_CLIENT_ID=seu-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=seu-client-secret

# 🤖 OpenAI
OPENAI_API_KEY=sk-...
AI_ENABLED=true
OPENAI_MODEL=gpt-4o

# 🔗 CORS
CORS_ALLOW_ORIGINS=http://localhost:5173,https://seu-dominio.vercel.app

# 📊 Ambiente
ENVIRONMENT=development  # ou production
LOG_LEVEL=INFO

Frontend (.env ou Vercel Environment Variables)

# 🔗 API
VITE_API_URL=http://localhost:8000/api/v1

# 🌐 Google OAuth (Chave Pública)
VITE_GOOGLE_CLIENT_ID=seu-client-id.apps.googleusercontent.com

# ⚙️ Configuração
VITE_APP_TITLE=Holocron Analytics

💻 Stack Tecnológico Detalhado

Backend (Python 3.12)

Frontend (Node.js 20+)

Infraestrutura

🚀 Como Executar

Pré-requisitos

• Docker & Docker Compose (Recomendado)

Executando com Docker

1. Na raiz do projeto:

   docker-compose -f docker-compose.dev.yml up -d --build
   

2. Acesse:

   • Frontend: http://localhost:5173
   • Docs: http://localhost:8000/docs

👨‍💻 Desenvolvedor

Projeto entregue para o Desafio Técnico PowerOfData.

"Faça ou não faça. Tentativa não há." — Mestre Yoda