How franciscomoretti/sparka works
Project Type & Purpose
• This is a full-stack, production-ready AI chat application built on Next.js 15 App Router.
• It provides a unified interface to 70+ AI models (Claude, GPT-4, Gemini, Grok, etc.) with features like document analysis, image generation, code execution, chat branches, resumable streams, deep research, and chat sharing.
• Key tech: Next.js (React Server Components), TypeScript, Tailwind, Vercel AI SDK, tRPC, Drizzle ORM, PostgreSQL, Redis.
File-Structure Analysis
• app/: Next.js App Router folder with top-level routes and nested layouts.
• (auth) and (chat) segments partition authorization and chat UIs.
• app/api/...: API routes for NextAuth, custom chat-model calls, cron tasks, file uploads, tRPC endpoint.
• components/: Shared React components & UI primitives.
• lib/: Core services & domain logic: AI integration (lib/ai), DB (Drizzle in lib/db), credit/reservation, artifacts, utilities.
• trpc/: tRPC initialization, client, server, and routers.
• providers/: React context providers (model selection, chat state).
• scripts/: utilities (e.g., fetch-models).
• config files: drizzle.config.ts, next.config.ts, vercel.json, Docker/TOML for deployment.
README Insights
• Frontend & backend stacks are clearly separated.
• Emphasis on “unified AI provider integration” through Vercel AI SDK Gateway and fallback logic.
• DB migrations (Drizzle ORM) and optional Redis for real-time features/caching.
Main Components
a. Client / Browser
• Next.js React components (client & server-component mix)
• Zustand state for UI/UX state
b. Next.js Server
• React Server Components & SSR/Streaming
• App Router serving pages under app/
• API routes: NextAuth (app/api/auth), file upload, chat-model passthrough, cron cleanup
c. tRPC Layer
• tRPC server (trpc/server.tsx) & routers (trpc/routers/*.ts)
• tRPC client (trpc/query-client.ts) inside frontend
d. Business-Logic & Services
• AI integration service (lib/ai/*) using Vercel AI SDK Gateway
• Tooling logic (lib/ai/tools/…), prompts, token utils, model features
• Artifact management, credits reservation, chat-branch utils
e. Data Layer
• PostgreSQL via Drizzle ORM (lib/db/client.ts, migrations/, queries.ts)
• Redis (caching, rate limiting, resumable streams)
f. External Services
• AI providers (OpenAI, Anthropic, Google, etc.) through AI SDK Gateway
• Optional blob storage (file attachments) or Vercel’s built-in storage
• Email/sso providers via NextAuth
Relationships & Data Flow
• Client ⇄ Next.js Server (page requests, RSC streaming, hydration)
• Client → tRPC Client → tRPC Server → Business Logic
• Business Logic ↔ AI SDK Gateway ↔ External AI Providers
• Business Logic ↔ Drizzle ORM ↔ PostgreSQL
• Business Logic ↔ Redis (cache tokens, stream cursors, rate-limit)
• API routes for attachments and cron tasks interact directly with services and DB
• Cron cleanup triggered by serverless functions scheduled in Vercel
Architectural Patterns & Design Principles
• Server Components (Next.js) to minimize client bundle
• tRPC for end-to-end type safety between frontend & backend
• Layered Architecture: UI → API / Controllers → Services → Data Access
• Provider Pattern in React for model, chat, and settings contexts
• Hexagonal-ish separation: core logic in lib/ never directly tied to Next.js
• Streaming & Resumability using React streams + Redis to persist cursors