How azekowka/nfactorial works
Project type and purpose
• This is a full-stack Next.js web application (“Wanderlust”) for travelers to track visited/want-to-visit countries, generate AI-driven trip guides, and animate travel maps.
• The README confirms: React/Next.js frontend, Next.js API Routes backend, Upstash Redis for storage, external AI/search/map/auth providers.
File structure
• app/ – Next.js 13 App Router: pages, layouts, dynamic routes, API endpoints under app/api
• components/ – shared React UI components, organized by feature (ai-guide, map, dashboard, ui)
• data/ – static JSON (countries, globe)
• lib/ – business logic layer:
• actions (chat orchestration)
• agents & tools (LLM prompt pipelines, search, retrieve)
• streaming (token streaming, parsing)
• config & constants
• Redis wrapper (Upstash)
• public/ – static assets (images, provider logos, config)
• next.config.js, middleware.ts – app configuration, auth enforcement
• tsconfig.json, tailwind.config.ts, package.json – build tooling
README for additional insights
• Shows three core features: Visited-Places tracker, AI-powered guide, Map animation
• Lists third-party integrations: Clerk (auth), MapBox (map), Google & Groq (LLM), Tavily/Serper/SearxNG (search), Upstash Redis (storage)
Main components
a. Client (Browser)
• React components under app/ and components/
• UI workflows: Landing → Sign-in (Clerk) → Dashboard → Feature pages
b. Next.js Server
• App Router for SSR/CSR pages & layouts
• API Routes (app/api/*) exposing endpoints:
– /api/chat → chat.ts (lib/actions/chat)
– /api/advanced-search → advanced-search/route.ts
– /api/countries → countries route handlers
• Middleware.ts enforces Clerk authentication on dashboard routes
c. Business Logic Layer (lib/)
• Tool orchestration: lib/tools (search, question, video-search, retrieve)
• Agent pipelines: lib/agents (researcher, related questions)
• Streaming handlers: lib/streaming (token streaming, parse calls)
• Redis client & schema: lib/redis, lib/schema
• Config & models: lib/config, lib/constants
d. Data Storage
• Upstash Redis (Visited/Wishlist flags, chat history)
e. External Services
• Auth: Clerk
• MapBox (map rendering, interactive layers)
• AI Providers: Google Gemini, Groq Llama via AI SDK
• Search Providers: Tavily, Serper, SearxNG
f. Static Assets & Config
• data/ countries.json, globe.json
• public/config/models.json
Relationships and data flows
• User interacts with React UI → Next.js App Router
• UI calls API Route → Next.js Server
• API handler invokes lib/actions or lib/agents → may spawn lib/streaming pipelines
• Business logic reads/writes Upstash Redis via lib/redis
• Business logic calls external AI or Search APIs, returns streamed responses
• Next.js Server responds to client → UI updates
• Feature retrieves static JSON + MapBox library on client
Architectural patterns and principles
• Feature-first folder structure (app/, components/ai-guide, components/map)
• Layered separation: Presentation (React) → API Routes → Domain logic (lib) → Persistence/External
• Streaming pattern for AI responses
• Next.js App Router for nested layouts, SSR/CSR flexibility
• Middleware for cross-cutting concerns (auth)