{"id":50896121,"url":"https://github.com/wallacemt/aws-lab-quest","last_synced_at":"2026-06-16T00:02:20.864Z","repository":{"id":343868316,"uuid":"1179260924","full_name":"wallacemt/aws-lab-quest","owner":"wallacemt","description":" Plataforma de preparação para certificações AWS com gamificação, modos de estudo adaptativos e pipeline de conteúdo via IA.","archived":false,"fork":false,"pushed_at":"2026-06-04T03:15:36.000Z","size":83571,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-04T05:11:50.759Z","etag":null,"topics":["aws","certificacao","cloud","ec2","ecs","eks","fargate","lambda","rds","s3","wellarchitected"],"latest_commit_sha":null,"homepage":"https://aws-lab-quest.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wallacemt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-11T21:17:03.000Z","updated_at":"2026-06-01T15:09:05.000Z","dependencies_parsed_at":null,"dependency_job_id":"0c3b348f-0375-4991-b325-411b987bb621","html_url":"https://github.com/wallacemt/aws-lab-quest","commit_stats":null,"previous_names":["wallacemt/aws-lab-quest"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/wallacemt/aws-lab-quest","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wallacemt%2Faws-lab-quest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wallacemt%2Faws-lab-quest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wallacemt%2Faws-lab-quest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wallacemt%2Faws-lab-quest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wallacemt","download_url":"https://codeload.github.com/wallacemt/aws-lab-quest/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wallacemt%2Faws-lab-quest/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34385031,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","certificacao","cloud","ec2","ecs","eks","fargate","lambda","rds","s3","wellarchitected"],"created_at":"2026-06-16T00:02:19.753Z","updated_at":"2026-06-16T00:02:20.812Z","avatar_url":"https://github.com/wallacemt.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AWS Lab Quest\n\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"./awlq-app/public/logo.png\" alt=\"Critix Vault\" width=\"280\" /\u003e\n\n\u003e Plataforma de preparação para certificações AWS com gamificação, modos de estudo adaptativos e pipeline de conteúdo via IA.\n\n[![Next.js](https://img.shields.io/badge/Next.js-16-black?logo=next.js)](https://nextjs.org)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5-blue?logo=typescript)](https://typescriptlang.org)\n[![Prisma](https://img.shields.io/badge/Prisma-7-2D3748?logo=prisma)](https://prisma.io)\n[![BullMQ](https://img.shields.io/badge/BullMQ-5-red)](https://bullmq.io)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green)](LICENSE)\n\n---\n\n## O que é\n\n**AWS Lab Quest** é uma aplicação web em português voltada para quem está se preparando para certificações AWS. O app transforma o estudo em uma experiência de RPG: o aluno ganha XP, sobe de nível, desbloqueia conquistas e compete em um ranking em tempo real — tudo enquanto pratica questões e executa labs temáticos gerados com IA.\n\n### Modos de estudo\n\n| Modo | Descrição |\n|---|---|\n| **Lab** | Quests temáticas geradas por IA com contexto personalizado (ex: musica, games, esporte) |\n| **KC (Knowledge Check)** | Bateria de questões por serviço ou tópico para revisão pontual |\n| **Simulado** | Prova completa com timer, detecção de questões marcadas, revisão pré-envio e score final |\n\n### Gamificação\n\n- **XP \u0026 Níveis** — Cada atividade concede XP proporcional à dificuldade\n- **Badges por nível** — Artes geradas via Pollinations API, exibidas no perfil e compartilháveis\n- **12 Conquistas** — Desbloqueadas automaticamente por marcos de desempenho\n- **Leaderboard em tempo real** — Ranking ao vivo via Supabase Realtime\n\n---\n\n## Arquitetura\n\n```\n┌─────────────────────────────────┐     ┌──────────────────────┐\n│          awlq-app               │     │     awlq-worker      │\n│        (Next.js 16)             │     │  (BullMQ + Node.js)  │\n│                                 │     │                      │\n│  App Router ─ API Routes        │     │  source-fetch        │\n│  Zustand ─ Framer Motion        │     │  question-generation │\n│  Better Auth ─ Prisma           │     │  feedback-analysis   │\n│  Supabase Realtime              │◄────│  performance-compute │\n│                                 │     │  quality-review      │\n└────────────┬────────────────────┘     │  email-send          │\n             │                         └──────────┬───────────┘\n             ▼                                    ▼\n      ┌──────────────┐              ┌─────────────────────────┐\n      │  PostgreSQL  │              │  Redis (BullMQ queues)  │\n      └──────────────┘              └─────────────────────────┘\n             │\n      ┌──────┴──────┐\n      │  Supabase   │  ← Storage (avatars, badges) + Realtime\n      └─────────────┘\n```\n\nO **app** serve o frontend e expõe as APIs REST. O **worker** roda separado, consome filas BullMQ e executa tarefas pesadas (geração de questões via Gemini, análise de feedback, envio de emails) sem bloquear a requisição do usuário.\n\n---\n\n## Stack\n\n### awlq-app (Frontend + API)\n| Camada | Tecnologia |\n|---|---|\n| Framework | Next.js 16 (App Router) + React 19 |\n| Linguagem | TypeScript 5 |\n| Estilo | Tailwind CSS 4 + Radix UI |\n| Auth | Better Auth 1.5 (email/senha, sessões) |\n| ORM | Prisma 7 + PostgreSQL |\n| Storage \u0026 Realtime | Supabase |\n| AI | Google Gemini API (`@google/generative-ai`) |\n| Estado | Zustand 5 |\n| Animações | Framer Motion 12 |\n| Email | Nodemailer (Gmail SMTP) |\n\n### awlq-worker (Background Jobs)\n| Camada | Tecnologia |\n|---|---|\n| Filas | BullMQ 5 + IORedis |\n| ORM | Prisma 7 (DB compartilhado) |\n| AI | Google Gemini API |\n| Logs | Pino 9 |\n| Runtime | Node.js 22 / Bun |\n\n---\n\n## Pré-requisitos\n\n- Node.js 22+ (ou Bun)\n- Docker + Docker Compose\n- Conta Google Cloud com Gemini API habilitada\n- Projeto Supabase (Storage + Realtime)\n- Conta Gmail com App Password habilitado\n\n---\n\n## Configuração Local\n\n### 1. Clone e instale dependências\n\n```bash\ngit clone https://github.com/seu-usuario/aws-lab-quest.git\ncd aws-lab-quest\n\n# App\ncd awlq-app \u0026\u0026 npm install\ncd ../awlq-worker \u0026\u0026 npm install\ncd ..\n```\n\n### 2. Configure variáveis de ambiente\n\n```bash\ncp .env.example awlq-app/.env\ncp .env.example awlq-worker/.env\n```\n\nEdite os arquivos `.env` preenchendo as variáveis descritas na seção abaixo.\n\n### 3. Suba os serviços de infraestrutura\n\n```bash\ndocker compose up -d postgres redis\n```\n\n\u003e O `docker-compose.yml` na raiz orquestra todos os serviços. Para desenvolvimento, suba apenas `postgres` e `redis` e rode o app/worker localmente.\n\n### 4. Configure o banco de dados\n\n```bash\ncd awlq-app\nnpm run db:generate   # gera o Prisma Client\nnpm run db:migrate    # aplica as migrations\nnpm run db:seed       # popula dados iniciais (badges, conquistas, serviços AWS)\n```\n\n### 5. Inicie os serviços\n\nEm terminais separados:\n\n```bash\n# Terminal 1 — App Next.js\ncd awlq-app \u0026\u0026 npm run dev\n\n# Terminal 2 — Worker BullMQ\ncd awlq-worker \u0026\u0026 npm run dev\n```\n\nAcesse: **http://localhost:3000**\n\n---\n\n## Variáveis de Ambiente\n\nCrie os arquivos `.env` baseados no [`.env.example`](.env.example).\n\n### Obrigatórias\n\n| Variável | Descrição |\n|---|---|\n| `DATABASE_URL` | URL de conexão PostgreSQL |\n| `REDIS_URL` | URL do Redis (ex: `redis://localhost:6379`) |\n| `BETTER_AUTH_SECRET` | String aleatória ≥ 32 caracteres |\n| `BETTER_AUTH_URL` | URL base da aplicação |\n| `GEMINI_API_KEY` | Chave da Google Generative AI |\n| `SUPABASE_URL` | URL do projeto Supabase |\n| `SUPABASE_SERVICE_ROLE_KEY` | Service role JWT do Supabase |\n| `SUPABASE_ANON_KEY` | Anon key do Supabase |\n| `MAIL_USERNAME` | Email Gmail para envio |\n| `MAIL_PASSWORD` | App Password do Gmail |\n\n### Opcionais\n\n| Variável | Padrão | Descrição |\n|---|---|---|\n| `GEMINI_MODEL` | `gemini-2.5-flash` | Modelo Gemini para geração |\n| `POLLINATIONS_API_KEY` | — | Chave para geração de imagens de badges |\n| `ADMIN_EMAIL` | — | Email do admin inicial (seed) |\n| `ADMIN_PASSWORD` | — | Senha do admin inicial (seed) |\n| `WEAK_AREA_THRESHOLD` | `0.60` | Taxa mínima de acerto para área fraca |\n| `TRIGGER_POLL_INTERVAL_MS` | `30000` | Intervalo do poller de triggers (ms) |\n| `LOG_LEVEL` | `info` | Nível de log do worker |\n\n---\n\n## Deploy com Docker\n\nPara produção, suba todos os serviços de uma vez:\n\n```bash\n# Crie a rede externa (apenas uma vez)\ndocker network create rt-network\n\n# Build e start\ndocker compose up -d --build\n```\n\nOs serviços `rt-awslq-app` (porta 3000) e `rt-awslq-worker` sobem na rede `rt-network`.\n\n```bash\ndocker compose logs -f          # acompanhar logs\ndocker compose down             # parar tudo\ndocker compose restart worker   # reiniciar só o worker\n```\n\n---\n\n## Estrutura do Projeto\n\n```\naws-lab-quest/\n├── awlq-app/               # Next.js app (frontend + API)\n│   ├── src/\n│   │   ├── app/            # App Router (páginas e API routes)\n│   │   ├── components/     # Componentes reutilizáveis (ui/, layout/)\n│   │   ├── features/       # Lógica por domínio (study/, admin/, user/)\n│   │   ├── hooks/          # Custom hooks React\n│   │   ├── lib/            # Utilitários, auth, prisma, AI\n│   │   └── stores/         # Zustand stores\n│   └── prisma/             # Schema, migrations, seed\n│\n├── awlq-worker/            # Worker BullMQ (processamento em background)\n│   └── src/\n│       ├── workers/        # Processadores de fila (email, geração, análise)\n│       ├── services/       # Lógica de negócio (AI, email, blueprint)\n│       ├── cron/           # Jobs agendados\n│       └── queues/         # Definições de filas BullMQ\n│\n├── docs/                   # Documentação técnica complementar\n├── docker-compose.yml\n└── .env.example\n```\n\n---\n\n## Fluxos Principais\n\n### Exam Guide e Simulado\n\n1. Admin envia o guia oficial em **`/admin/upload`** (tipo: Exam Guide)\n2. Sistema extrai blueprint de domínios e pesos automaticamente\n3. Sem Exam Guide, o endpoint de questões retorna erro de bloqueio\n4. Admin envia PDF de simulado para ingestão de questões\n\n### Pipeline de Questões via IA\n\n```\nPDF/Markdown → Extração → Segmentação de blocos → Gemini API\n→ Validação (schema, mínimo de opções) → Deduplicação (usageHash)\n→ Persistência no banco\n```\n\nO worker também gera variantes mais difíceis de questões já respondidas automaticamente para evitar repetição em simulados futuros.\n\n### Conquistas\n\nDesbloqueadas automaticamente ao salvar histórico de lab/KC/simulado. A galeria em `/achievements` exibe progresso, unlock e link público de compartilhamento.\n\n---\n\n## Documentação Técnica\n\n| Documento | Descrição |\n|---|---|\n| [achievements-system.md](docs/achievements-system.md) | Sistema de conquistas e desbloqueio |\n| [simulado-pdf-pipeline.md](docs/tech/simulado-pdf-pipeline.md) | Pipeline PDF → Questão |\n| [platform-upgrade-2026-03.md](docs/platform-upgrade-2026-03.md) | Arquitetura e melhorias recentes |\n| [question-ingestion-refactor-2026-03.md](docs/tech/question-ingestion-refactor-2026-03.md) | Refactor do worker de ingestão |\n| [create-lab-quest-v1.md](docs/showcase/labs/create-lab-quest-v1.md) | Como criar um Lab Quest |\n| [CONTRIBUTING.md](CONTRIBUTING.md) | Como contribuir com o projeto |\n\n---\n\n## Contribuindo\n\nContribuições são bem-vindas! Leia o [guia de contribuição](CONTRIBUTING.md) para saber como reportar bugs, sugerir melhorias e enviar pull requests.\n\n---\n\n## Licença\n\nMIT © [AWS Lab Quest Contributors](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwallacemt%2Faws-lab-quest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwallacemt%2Faws-lab-quest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwallacemt%2Faws-lab-quest/lists"}