Update README.md
🚀 PROJETO JETLY - PROMPT COMPLETO DE DESENVOLVIMENTO
- VISÃO GERAL DO PROJETO
1.1 O Que é o JETLY?
O JETLY é uma plataforma digital verticalizada de locação de Jet Skis que conecta proprietários de jetskis a locatários através de um marketplace fechado e seguro. A plataforma padroniza um mercado informal, oferecendo segurança, conveniência e monetização previsível através de assinaturas mensais obrigatórias para proprietários e taxa de 2% sobre cada transação paga pelo locatário.
1.2 Diferenciais Competitivos
· Foco exclusivo: Apenas locação de Jet Skis (não é um marketplace genérico)
· Modelo fechado: Todo ciclo (chat, pagamento, avaliação) ocorre dentro da plataforma
· Monetização dupla: Assinaturas recorrentes + comissão por transação
· Padronização automática: Sugestão inteligente de preços baseada em marca, modelo, ano e conservação
· Segurança financeira: Sistema de escrow que libera pagamento apenas após uso confirmado
1.3 Público-Alvo
· Proprietários: Donos de jetskis individuais, pequenas frotas, empresas de turismo
· Locatários: Turistas, entusiastas, empresas em eventos, usuários casuais
- ARQUITETURA DO SISTEMA
2.1 Arquitetura Geral (Monolítica Moderna com Separação Clara)
┌─────────────────────────────────────────────────────────────┐
│ CLIENTE (Frontend React) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Pages │ │Components│ │ Hooks │ │ Styles │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└──────────────────────────┬──────────────────────────────────┘
│ HTTP(S) + WebSocket
┌──────────────────────────▼──────────────────────────────────┐
│ SERVER (Backend Node.js) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ tRPC │ │ Business │ │ Database │ │ External │ │
│ │ Router │ │ Logic │ │ Layer │ │ APIs │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└──────────────────────────┬──────────────────────────────────┘
│
┌──────────────────────────▼──────────────────────────────────┐
│ INFRAESTRUTURA E SERVIÇOS │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ MySQL │ │ Stripe │ │ Google │ │ S3 │ │
│ │ Database │ │ Payments │ │ Maps │ │ Storage │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────┘
2.2 Padrão Arquitetural: tRPC-First
Ao invés do tradicional REST API, utilizamos tRPC que oferece:
· Type-safety end-to-end: Tipos TypeScript compartilhados entre frontend e backend
· Zero boilerplate: Elimina necessidade de definir schemas OpenAPI/Swagger
· Desenvolvimento rápido: Alterações no backend refletem imediatamente no frontend
· Protocolo eficiente: Usa JSON-RPC 2.0 sobre HTTP
2.3 Fluxo de Dados Principal
1. Cliente → tRPC Client (React Hook)
2. HTTP POST /api/trpc/{procedure}
3. tRPC Server (Router + Procedure)
4. Validação (Zod) → Business Logic
5. Database Access (Drizzle ORM)
6. Resposta (SuperJSON)
7. Cliente recebe dados tipados
- STACK TECNOLÓGICA DETALHADA
3.1 Frontend (Aplicação Web React)
Tecnologia Versão Propósito Justificativa
React 19.2.1 Framework UI Hooks modernos, Concurrent Features
TypeScript 5.9.3 Type Safety Redução de bugs, melhor autocomplete
Tailwind CSS 4.1.14 Estilização Utility-first, customização Art Deco
Vite 7.1.7 Build Tool Dev server rápido, HMR instantâneo
wouter 3.3.5 Roteamento Leve (2kb), hooks-based, simples
React Query 5.62.3 Gerenciamento estado server Cache, retry, optimistic updates
Framer Motion 12.23.22 Animações Declarativo, performático, simples
Lucide React 0.453.0 Ícones SVG, tree-shakeable, consistente
React Hook Form 7.64.0 Formulários Performance, validação integrada
Zod 4.1.12 Validação TypeScript-first, schema validation
3.2 Backend (Node.js + tRPC)
Tecnologia Versão Propósito Justificativa
Node.js 22.13.0 Runtime LTS, async/await, ecosystem
Express 4.21.2 Web Framework Minimalista, middleware ecosystem
tRPC 11.6.0 RPC Framework Type-safety, desenvolvimento rápido
Drizzle ORM 0.44.5 Database ORM Type-safe, SQL-like, migrations
MySQL2 3.15.0 Database Driver Promise-based, performático
SuperJSON 1.13.3 Serialização Dates, Maps, Sets, BigInt support
Jose 6.1.0 JWT Standards-compliant, seguro
Socket.io 4.8.1 WebSockets Chat em tempo real, rooms
Multer + S3 - Upload files Stream direto para AWS S3
3.3 Banco de Dados
Tecnologia Configuração Justificativa
MySQL 8.0+ RDS/Aurora ou TiDB Transacional, ACID, maduro
Schema Design Normalizado + índices estratégicos Performance queries complexas
Índices (userId, createdAt), (location, isActive) Buscas rápidas
Backup Automático diário + point-in-time recovery Segurança dados
3.4 Serviços Externos & APIs
Serviço Uso Integração
Manus OAuth Autenticação SSO OAuth 2.0 flow
Stripe Pagamentos + Assinaturas REST API + Webhooks
Google Maps Geolocalização + Mapas JavaScript SDK
AWS S3 Armazenamento fotos/vídeos AWS SDK
Manus Notification Emails transacionais REST API
Twilio SMS (futuro) REST API
3.5 DevOps & Infraestrutura
Ferramenta Uso Configuração
GitHub Actions CI/CD Auto-deploy em push
Docker Containerização Multi-stage builds
Vercel Frontend hosting Automatic preview deploys
Railway/Render Backend hosting Node.js + MySQL
CloudFlare CDN + DNS + Security WAF, DDoS protection
Sentry Error Monitoring Real-time error tracking
Plausible Analytics Privacy-friendly
- ESTRUTURA DE PASTAS COMPLETA
jetly/
├── .github/
│ └── workflows/
│ ├── ci.yml # Testes automatizados
│ └── cd.yml # Deploy automático
├── apps/
│ ├── web/ # Aplicação React principal
│ │ ├── public/ # Assets estáticos
│ │ └── src/
│ │ ├── pages/ # Páginas da aplicação
│ │ │ ├── Home.tsx
│ │ │ ├── Browse.tsx
│ │ │ ├── Dashboard/
│ │ │ ├── JetSki/
│ │ │ └── Checkout/
│ │ ├── components/ # Componentes reutilizáveis
│ │ │ ├── ui/ # shadcn/ui inspired
│ │ │ ├── layout/ # Layout components
│ │ │ └── shared/ # Shared components
│ │ ├── hooks/ # Custom React hooks
│ │ │ ├── useAuth.ts
│ │ │ └── useNotifications.ts
│ │ ├── lib/ # Configurações e clients
│ │ │ ├── trpc.ts
│ │ │ ├── stripe.ts
│ │ │ └── maps.ts
│ │ ├── styles/ # Estilos globais
│ │ │ └── art-deco.css
│ │ └── utils/ # Funções utilitárias
│ │
│ └── api/ # Backend tRPC + Express
│ ├── src/
│ │ ├── core/ # Configurações core
│ │ │ ├── trpc.ts
│ │ │ ├── context.ts
│ │ │ └── middleware.ts
│ │ ├── routers/ # tRPC routers
│ │ │ ├── index.ts
│ │ │ ├── auth.router.ts
│ │ │ ├── jetskis.router.ts
│ │ │ └── bookings.router.ts
│ │ ├── services/ # Lógica de negócio
│ │ │ ├── auth.service.ts
│ │ │ ├── pricing.service.ts
│ │ │ └── notification.service.ts
│ │ ├── db/ # Database layer
│ │ │ ├── schema.ts
│ │ │ ├── helpers/
│ │ │ └── migrations/
│ │ └── utils/ # Utilitários backend
│ └── server.ts # Entry point Express
│
├── packages/ # Pacotes compartilhados
│ ├── database/ # Drizzle schema shared
│ ├── types/ # Tipos TypeScript compartilhados
│ ├── utils/ # Utilitários compartilhados
│ └── config/ # Configurações ESLint/Prettier
│
├── tooling/ # Ferramentas desenvolvimento
│ ├── scripts/ # Scripts utilitários
│ └── generators/ # Plop templates
│
├── docs/ # Documentação
│ ├── api/ # API documentation
│ ├── database/ # Schema documentation
│ └── deployment/ # Guias de deploy
│
└── tests/ # Testes E2E
├── e2e/
└── fixtures/
- DETALHES TÉCNICOS DE IMPLEMENTAÇÃO
5.1 Autenticação & Autorização
// Sistema baseado em sessão com cookies HTTP-only
export const authRouter = router({
login: publicProcedure
.input(z.object({ code: z.string() })) // OAuth code
.mutation(async ({ input, ctx }) => {
// 1. Trocar code por token (Manus API)
// 2. Criar/atualizar usuário no DB
// 3. Gerar JWT session token
// 4. Setar cookie HTTP-only
// 5. Retornar user data (sem sensitive info)
}),
me: protectedProcedure.query(({ ctx }) => {
return ctx.user; // Injetado pelo middleware
}),
logout: publicProcedure.mutation(({ ctx }) => {
// Clear cookie
ctx.res.clearCookie('jetly_session');
return { success: true };
})
});
5.2 Sistema de Preços Automático
class PricingService {
calculateSuggestedPrice(jetski: JetSkiInput): number {
// Base price por marca
const brandBase: Record<string, number> = {
'Sea-Doo': 15000, // R$ 150/hora em centavos
'Yamaha': 14000,
'Kawasaki': 13000,
'BRP': 15000,
};
let price = brandBase[jetski.brand] || 12000;
// Depreciação por ano (5% ao ano)
const currentYear = new Date().getFullYear();
const age = currentYear - jetski.year;
const depreciation = Math.max(0.5, 1 - (age * 0.05));
price = Math.round(price * depreciation);
// Multiplicador por condição
const conditionMultiplier: Record<Condition, number> = {
'excellent': 1.2,
'good': 1.0,
'fair': 0.8,
'needs_repair': 0.5,
};
price = Math.round(price * conditionMultiplier[jetski.condition]);
// Arredondamento para múltiplo de 500 (R$ 5)
return Math.round(price / 500) * 500;
}
}
5.3 Sistema de Escrow (Garantia)
// Fluxo de pagamento com escrow
async function processBookingPayment(booking: Booking) {
// 1. Criar PaymentIntent no Stripe
const paymentIntent = await stripe.paymentIntents.create({
amount: booking.totalPrice,
currency: 'brl',
metadata: { bookingId: booking.id },
capture_method: 'manual', // Não capturar imediatamente
});
// 2. Criar registro de pagamento com status "held"
await db.payments.create({
data: {
bookingId: booking.id,
amount: booking.totalPrice,
status: 'held',
stripePaymentIntentId: paymentIntent.id,
}
});
// 3. Webhook do Stripe confirma quando usuário paga
// 4. Após uso confirmado, liberar para proprietário
await stripe.paymentIntents.capture(paymentIntent.id);
await db.payments.update({
where: { bookingId: booking.id },
data: { status: 'released' }
});
}
5.4 Chat em Tempo Real com Anti-Fraude
// Configuração Socket.io com rooms por booking
io.on('connection', (socket) => {
socket.on('join-booking', (bookingId) => {
socket.join(`booking:${bookingId}`);
});
socket.on('message', async (data) => {
// Verificação anti-fraude
const hasPhone = /(\+55|\(\d{2}\)|\d{4,5}\-?\d{4})/.test(data.content);
const hasExternalLink = /(whatsapp\.|telegram\.|http(s)?:\/\/)/i.test(data.content);
if (hasPhone || hasExternalLink) {
// Bloquear mensagem e notificar admin
socket.emit('message-blocked', { reason: 'Conteúdo não permitido' });
await db.chatMessages.create({
data: {
...data,
isFlagged: true,
flagReason: hasPhone ? 'phone_number' : 'external_link'
}
});
return;
}
// Mensagem válida - broadcast para room
const message = await db.chatMessages.create({ data });
io.to(`booking:${data.bookingId}`).emit('new-message', message);
});
});
- MODELO DE BANCO DE DADOS PRINCIPAL
-- Tabela principal de Jet Skis
CREATE TABLE jet_skis (
id INT PRIMARY KEY AUTO_INCREMENT,
owner_id INT NOT NULL,
brand VARCHAR(100) NOT NULL,
model VARCHAR(100) NOT NULL,
year INT NOT NULL,
condition ENUM('excellent', 'good', 'fair', 'needs_repair') NOT NULL,
location VARCHAR(255) NOT NULL,
latitude DECIMAL(10, 8),
longitude DECIMAL(11, 8),
current_price INT NOT NULL COMMENT 'em centavos',
base_price INT NOT NULL,
rating DECIMAL(3, 2) DEFAULT 0.00,
review_count INT DEFAULT 0,
is_active BOOLEAN DEFAULT TRUE,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
INDEX idx_location (location),
INDEX idx_owner_active (owner_id, is_active),
SPATIAL INDEX idx_coords (latitude, longitude),
FOREIGN KEY (owner_id) REFERENCES users(id) ON DELETE CASCADE
);
-- Tabela de reservas com cálculo de taxa
CREATE TABLE bookings (
id INT PRIMARY KEY AUTO_INCREMENT,
jetski_id INT NOT NULL,
renter_id INT NOT NULL,
owner_id INT NOT NULL,
start_time DATETIME NOT NULL,
end_time DATETIME NOT NULL,
duration_minutes INT NOT NULL,
base_price INT NOT NULL COMMENT 'preço base do jetski',
platform_fee INT NOT NULL COMMENT '2% do base_price',
total_price INT NOT NULL COMMENT 'base_price + platform_fee',
status ENUM('pending', 'confirmed', 'completed', 'cancelled') DEFAULT 'pending',
stripe_payment_id VARCHAR(255),
INDEX idx_owner_status (owner_id, status),
INDEX idx_renter_status (renter_id, status),
INDEX idx_jetski_time (jetski_id, start_time),
FOREIGN KEY (jetski_id) REFERENCES jet_skis(id) ON DELETE CASCADE
);
- PLANO DE DESENVOLVIMENTO FASEADO
FASE 1: FUNDAÇÃO (2 semanas)
· Setup monorepo com turborepo
· Configuração TypeScript, ESLint, Prettier
· Banco de dados local com Docker
· Autenticação OAuth com Manus
· Tema Tailwind Art Deco
· Deploy automático CI/CD
FASE 2: CORE PROPRIETÁRIO (3 semanas)
· Cadastro de Jet Skis (form + upload)
· Dashboard proprietário
· Sistema de assinaturas (Stripe)
· Cálculo automático de preços
· Gestão de disponibilidade
FASE 3: MARKETPLACE (3 semanas)
· Busca com filtros avançados
· Mapa interativo Google Maps
· Página detalhada do Jet Ski
· Sistema de reservas
· Checkout com taxa de 2%
FASE 4: COMUNICAÇÃO (2 semanas)
· Chat em tempo real
· Sistema de notificações
· Avaliações duplas
· Email transacional
FASE 5: POLIMENTO (2 semanas)
· SEO otimizado
· PWA capabilities
· Testes E2E
· Performance optimization
· Deploy produção
- TESTES & QUALIDADE
8.1 Estratégia de Testes
// Testes unitários (Vitest)
describe('PricingService', () => {
it('calcula preço correto para Sea-Doo 2023 excelente', () => {
const price = pricingService.calculateSuggestedPrice({
brand: 'Sea-Doo',
model: 'GTX 300',
year: 2023,
condition: 'excellent'
});
expect(price).toBeGreaterThan(0);
expect(price).toBeLessThan(100000);
});
});
// Testes de integração
describe('Booking flow', () => {
it('cria reserva e processa pagamento', async () => {
const booking = await createBookingTest();
const payment = await processPayment(booking);
expect(payment.status).toBe('held');
});
});
// Testes E2E (Cypress)
describe('User journey', () => {
it('completa reserva end-to-end', () => {
cy.login();
cy.searchJetSki();
cy.selectDateTime();
cy.completePayment();
cy.confirmBooking();
});
});
8.2 Métricas de Qualidade
· Coverage mínimo: 80% (unit), 60% (integration)
· Lighthouse score: >90 Performance, >90 Accessibility
· Load testing: Suporta 1000 usuários simultâneos
· Security: Passa OWASP Top 10 checks
- SEGURANÇA & COMPLIANCE
9.1 Medidas de Segurança
· OWASP Top 10: Proteção contra XSS, CSRF, SQL Injection
· GDPR/LGPD: Cookie consent, data encryption, right to delete
· PCI DSS: Stripe handling (não armazenamos dados de cartão)
· Data encryption: AES-256 em repouso, TLS 1.3 em trânsito
9.2 Monitoramento
· Sentry: Error tracking real-time
· LogRocket: Session replay para debugging
· Uptime Robot: Monitoramento disponibilidade
· Security headers: HSTS, CSP, X-Frame-Options
- ESCALABILIDADE & PERFORMANCE
10.1 Otimizações Iniciais
· CDN: CloudFlare para assets estáticos
· Caching: Redis para queries frequentes
· Image optimization: WebP + lazy loading
· Database indexing: Índices estratégicos
10.2 Plano de Escala
· Fase 1: Single server + MySQL
· Fase 2: Load balancer + read replicas
· Fase 3: Microservices para chat/pagamentos
· Fase 4: Kubernetes cluster
- IMPLANTAÇÃO & DEVOPS
11.1 Pipeline CI/CD
# .github/workflows/deploy.yml
name: Deploy
on: [push]
jobs:
test:
runs-on: ubuntu-latest
steps:
- run: pnpm test
- run: pnpm build
deploy-staging:
needs: test
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
steps:
- run: pnpm deploy:staging
deploy-prod:
needs: test
if: github.ref == 'refs/heads/production'
runs-on: ubuntu-latest
steps:
- run: pnpm deploy:production
11.2 Infraestrutura como Código
# Terraform para AWS
resource "aws_rds_cluster" "jetly_db" {
cluster_identifier = "jetly-prod"
engine = "aurora-mysql"
database_name = "jetly"
master_username = "admin"
master_password = var.db_password
backup_retention_period = 30
preferred_backup_window = "07:00-09:00"
}
- DOCUMENTAÇÃO & ONBOARDING
12.1 Documentação Incluída
· docs/development.md - Setup local
· docs/api.md - API reference
· docs/database.md - Schema e migrations
· docs/deployment.md - Guia de deploy
· docs/business-logic.md - Regras de negócio
12.2 Scripts de Desenvolvimento
{
"scripts": {
"dev": "turbo dev",
"build": "turbo build",
"test": "turbo test",
"db:push": "drizzle-kit push",
"db:studio": "drizzle-kit studio",
"type-check": "turbo type-check",
"lint": "turbo lint",
"format": "prettier --write ."
}
}
- ENTREGÁVEIS FINAIS
13.1 Código Fonte
· Repositório Git completo com histórico
· 100% TypeScript com tipagem estrita
· Testes unitários e de integração
· Dockerfiles para desenvolvimento/produção
13.2 Infraestrutura
· Ambiente de staging configurado
· Pipeline CI/CD funcionando
· Banco de dados com dados de exemplo
· Monitoring e alertas configurados
13.3 Documentação
· Manual técnico completo
· Guia de deploy em produção
· API documentation (OpenAPI)
· Runbook para operações
PRÓXIMOS PASSOS
Confirmar stack tecnológica - Validar escolhas com time
Setup ambiente desenvolvimento - Docker local + banco
Desenvolver MVP core - Autenticação + cadastro jetskis
Testar fluxo principal - Busca → Reserva → Pagamento
Polir UX/UI - Design Art Deco refinado
Preparar produção - Deploy + monitoring
🎯 RESUMO EXECUTIVO TÉCNICO
O JETLY será desenvolvido como uma aplicação web moderna com arquitetura monolítica bem estruturada, utilizando tRPC para type-safety end-to-end, React 19 com hooks, Tailwind CSS para estilização, MySQL com Drizzle ORM, e Stripe para pagamentos.
Diferenciais técnicos:
- Type-safety completo - TypeScript em todas as camadas
- Developer experience excelente - Hot reload, autocomplete
- Performance otimizada - Code splitting, image optimization
- Segurança robusta - OAuth, escrow, anti-fraude
- Escalabilidade planejada - Arquitetura preparada para crescimento
Timeline: 12 semanas para MVP completo
Custo estimado:R$ 140.000 (incluindo infraestrutura anual)
Equipe:2 desenvolvedores sênior full-stack
Pronto para iniciar desenvolvimento? 🚀
Este prompt cobre 100% do projeto JETLY com profundidade técnica, padrões profissionais, e roadmap executável. Posso começar a implementação imediatamente, começando pela Fase 1 (Setup e Fundação).