🛡️ AegisWallet

Voice-First Autonomous Financial Assistant for Brazil

AegisWallet is an intelligent financial management platform designed specifically for the Brazilian market, featuring voice-first interaction, PIX integration, and progressive AI autonomy (50% → 95% automation).

📅 Integração Google Calendar

O AegisWallet oferece sincronização bidirecional com Google Calendar, permitindo que você:

Sincronize eventos financeiros com sua agenda do Google
Crie eventos arrastando e soltando no calendário
Mantenha seus compromissos financeiros sempre atualizados
Controle quais dados são sincronizados (privacidade LGPD)

Configuração

Acesse as configurações do calendário
Clique em "Conectar Google Calendar"
Autorize o acesso à sua conta Google
Configure as opções de sincronização

Para mais detalhes, consulte a documentação completa.

🚀 Quick Start

# Install dependencies
bun install

# Start development server (client + server)
bun dev:full

# Or start separately
bun dev:client  # Vite dev server (port 8080)
bun dev:server  # Hono server (port 3000)

# Run tests
bun test

# Validate code quality
bun quality

🗄️ Database Setup (Neon PostgreSQL)

1. Environment Configuration

# Copy environment template
cp env.example .env

# Edit .env and add your Neon connection strings
# DATABASE_URL=postgresql://... (pooled connection)
# DATABASE_URL_UNPOOLED=postgresql://... (direct connection)

2. Verify Database Connection

# Run comprehensive setup verification
bun run neon:verify

# Quick connection test
bun run smoke:db

3. Apply Database Migrations

# Generate migrations from schema changes
bun db:generate

# Apply migrations to database
bun db:migrate

# Or push schema directly (development only)
bun db:push

4. Start Development Servers

# Start both frontend and backend with validation
bun dev:full

# Or start separately:
bun dev:client  # Frontend on http://localhost:8080
bun dev:server  # Backend on http://localhost:3000

5. Validate Integration

# Test frontend-backend-database connectivity
bun run integration:test

# Check health endpoint
curl http://localhost:3000/api/health

📚 Database Documentation

For complete setup instructions, see:

🔧 Available Database Scripts

Command	Description
`bun neon:verify`	Verify complete Neon DB setup
`bun neon:test`	Quick database connection test
`bun db:generate`	Generate migrations from schema
`bun db:migrate`	Apply migrations
`bun db:push`	Push schema directly (dev)
`bun db:studio`	Open Drizzle Studio
`bun db:health`	Run comprehensive health check
`bun integration:test`	Test full stack integration

🔐 Authentication Setup

AegisWallet uses Clerk for authentication and user management.

Setup Guide: For complete setup instructions, see Clerk Setup Guide
Quick Start: Add VITE_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY to .env (see env.example for details)

💳 Billing System

AegisWallet uses Stripe for subscription billing with three tiers:

Gratuito: Dashboard básico e recursos limitados
Básico (R$ 59/mês): Chat IA + automações básicas
Avançado (R$ 119/mês): Todos os modelos de IA + recursos premium

Setup

Configure Stripe: See Stripe Setup Guide
Configure Clerk Webhooks: See Clerk Integration Guide
Seed Plans: Run bun scripts/seed-subscription-plans.ts

API Endpoints

GET /api/v1/billing/subscription - Get current subscription
POST /api/v1/billing/checkout - Create checkout session
POST /api/v1/billing/portal - Access customer portal
GET /api/v1/billing/plans - List available plans
GET /api/v1/billing/payment-history - Get payment history

📖 Full Documentation: Billing API Reference

🎨 Design System

AegisWallet uses a semantic color token system for consistent, accessible UI design.

Color Tokens

Semantic States: success, warning, destructive, info
Financial: financial-positive, financial-negative, financial-neutral
PIX Branding: pix-primary, pix-accent

Usage Example

// ✅ DO: Use semantic tokens
<Badge className="bg-success/10 text-success">Completed</Badge>
<span className="text-financial-positive">+R$ 1.500,00</span>

// ❌ DON'T: Use hardcoded colors
<Badge className="bg-green-100 text-green-700">Completed</Badge>
<span className="text-green-600">+R$ 1.500,00</span>

Validation

# Validate color usage
bun run validate:colors

# Pre-commit hook automatically validates colors
git commit -m "feat: add new feature"

Styling: Tailwind CSS + shadcn/ui
Forms: React Hook Form + Zod

Backend

API: Hono RPC (edge-optimized)
ORM: Drizzle (type-safe, TCP connection)
Server: Hono (edge-optimized)
Auth: Clerk (User Management)
Database: Neon (Serverless Postgres) + Drizzle ORM

Quality

Testing: Vitest (unit) + Playwright (E2E)
Linting: OXLint (50-100x faster) + Biome
Type Safety: TypeScript strict mode
Git Hooks: Husky (pre-commit validation)

🔌 API Architecture

Hono RPC + Drizzle Architecture

AegisWallet uses Hono for edge-optimized HTTP handling and Drizzle ORM for type-safe database access.

Hono (Edge-First HTTP Framework)

Static File Serving: Hosts the built SPA assets
Health Endpoints: See Health Check Endpoints below
API Routes: RESTful endpoints under /api/v1/*
Middleware: CORS, authentication, rate limiting, logging

Health Check Endpoints

Endpoint	Status Codes	Purpose
`/api/ping`	Always 200	Liveness probe for load balancers and uptime monitors
`/api/health`	200 or 503	Deep health check including database connectivity
`/api/v1/ping`	Always 200	v1 API liveness probe
`/api/v1/health`	200 or 503	v1 API deep health check

Important: /api/health returns HTTP 503 when the database is unavailable. Use /api/ping for infrastructure health checks that only need to verify the server process is running.

Drizzle ORM (Type-Safe Database Layer)

Direct Connection: Connects to Neon PostgreSQL via serverless driver
Type Safety: Automatic TypeScript types from database schema
Query Builder: Composable, type-safe query building
Schema Introspection: Auto-generates schema from existing database

Router Organization

Core Routers

users: Profiles, preferences, financial summaries
transactions: CRUD with fraud detection, statistics
bank-accounts: Manual accounts, balances, history

Specialized Routers

contacts: Contact management with favorites
calendar: Financial events and reminders
google-calendar: Bidirectional sync with Google Calendar
voice: Voice command processing and analytics
banking: Open Finance integration

Key Features

✅ Type Safety – End-to-end TypeScript types from database to frontend ✅ Performance – Direct TCP connection eliminates HTTP overhead ✅ Validation – Zod schemas with @hono/zod-validator ✅ Security – JWT authentication, rate limiting, RLS policies ✅ Edge-Ready – Optimized for Vercel Edge Functions

Usage Example

// Server (Hono route with Drizzle)
import { db } from '@/db';
import { users } from '@/db/schema';
import { eq } from 'drizzle-orm';

usersRouter.get('/me', authMiddleware, async (c) => {
  const { user } = c.get('auth');
  const userData = await db
    .select()
    .from(users)
    .where(eq(users.id, user.id))
    .limit(1);
  return c.json({ data: userData[0] });
});

// Client (HTTP fetch)
const response = await fetch('/api/v1/users/me', {
  headers: { Authorization: `Bearer ${token}` }
});
const { data } = await response.json();

📖 Full Documentation: API Architecture Guide

📁 Project Structure

src/
├── components/          # React UI components
│   ├── ui/             # shadcn/ui components
│   ├── financial/      # Financial components
│   ├── pix/            # PIX components
│   └── voice/          # Voice interaction components
├── routes/             # TanStack Router pages
├── server/             # Backend Hono RPC server
│   ├── routes/         # API route handlers
│   ├── middleware/     # Server middleware
│   └── services/       # Business logic services
├── db/                 # Drizzle ORM database layer
│   ├── schema/         # Table schemas by domain
│   └── migrations/     # Database migrations
├── hooks/              # Custom React hooks
├── lib/                # Utility libraries
├── services/           # Business logic services
└── types/              # TypeScript type definitions

🧪 Testing

# Run all tests
bun test

# Run with coverage
bun test:coverage

# Run in watch mode
bun test:watch

# Run integration tests
bun test:integration

Coverage Target: 90%+ for critical business logic

🔍 Code Quality

# Run linting
bun lint

# Fix linting issues
bun lint:fix

# Run quality checks (lint + test + coverage)
bun quality

# CI mode (for pipelines)
bun quality:ci

Quality Gates

All code changes must pass:

✅ Automated tests (100% pass rate)
✅ Type checking (zero TypeScript errors)
✅ Linting (OXLint + Biome)
✅ Color validation (no hardcoded colors)
✅ Security scan (zero high-severity vulnerabilities)

🚢 Deployment

Local Build & Preview

# Build for production
bun build

# Start production server locally
bun start:prod

# Preview build
bun preview

Vercel Deployment

AegisWallet is optimized for Vercel deployment with native Hono and Vite support.

Quick Deploy

# 1. Setup environment variables
bun deploy:vercel:setup

# 2. Deploy to preview
bun deploy:vercel:preview

# 3. Deploy to production
bun deploy:vercel:prod

Manual Deployment

# Install Vercel CLI
bun add -g vercel

# Login to Vercel
vercel login

# Link project
vercel link

# Add environment variables
vercel env add VITE_CLERK_PUBLISHABLE_KEY production
vercel env add DATABASE_URL production
# ... (repeat for all variables)

# Deploy to preview
vercel

# Deploy to production
vercel --prod

Verify Deployment

# Check deployment status
bun deploy:vercel:check

# View logs
vercel logs [deployment-url]

📖 Full Documentation: Vercel Deployment Guide

📚 Documentation

🤝 Contributing

Development Workflow

Create a feature branch
Make changes following the style guide
Run quality checks: bun quality
Commit (pre-commit hooks will validate)
Push and create a pull request

Code Standards

Use semantic color tokens (never hardcoded colors)
Follow KISS and YAGNI principles
Maintain 90%+ test coverage for critical code
Write meaningful commit messages (conventional commits)
Ensure TypeScript strict mode compliance

📄 License

[Add your license here]

🙏 Acknowledgments

Built with:

Bun - Fast JavaScript runtime
React - UI library
Hono - Edge-first web framework
Drizzle ORM - Type-safe database ORM
Neon - Serverless Postgres
Clerk - Authentication
TanStack - Router & Query
Tailwind CSS - Styling
shadcn/ui - Component library

Made with ❤️ for the Brazilian market

skill-creator

🛡️ AegisWallet

📅 Integração Google Calendar

Configuração

🚀 Quick Start

🗄️ Database Setup (Neon PostgreSQL)

1. Environment Configuration

2. Verify Database Connection

3. Apply Database Migrations

4. Start Development Servers

5. Validate Integration

📚 Database Documentation

🔧 Available Database Scripts

🔐 Authentication Setup

💳 Billing System

Setup

API Endpoints

🎨 Design System

Color Tokens

Usage Example

Validation

Backend

Quality

🔌 API Architecture

Hono RPC + Drizzle Architecture

Hono (Edge-First HTTP Framework)

Health Check Endpoints

Drizzle ORM (Type-Safe Database Layer)

Router Organization

Core Routers

Specialized Routers

Key Features

Usage Example

📁 Project Structure

🧪 Testing

🔍 Code Quality

Quality Gates

🚢 Deployment

Local Build & Preview

Vercel Deployment

Quick Deploy

Manual Deployment

Verify Deployment

📚 Documentation

🤝 Contributing

Development Workflow

Code Standards

📄 License

🙏 Acknowledgments