# azekowka/nfactorial architecture

> Architecture diagram of the GitHub repository azekowka/nfactorial, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/azekowka/nfactorial
- Repository: https://github.com/azekowka/nfactorial

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TB
  subgraph "Presentation Layer"
    Browser["Client (Browser)"]:::frontend
    UIAppLayout["app/layout.tsx"]:::frontend
    UIAppPage["app/page.tsx"]:::frontend
    Nav["components/navbar.tsx"]:::frontend
    PageContainer["components/page-container.tsx"]:::frontend
  end

  subgraph "Next.js Server"
    subgraph "App Router"
      NextAppDir["app/"]:::server
      SignIn["app/sign-in/[[...sign-in]]/page.tsx"]:::server
      SignUp["app/sign-up/[[...sign-up]]/page.tsx"]:::server
      DashHome["app/dashboard/page.tsx"]:::server
      DashAI["app/dashboard/ai/page.tsx"]:::server
      DashMapAnim["app/dashboard/map-animate/page.tsx"]:::server
      DashWorld["app/dashboard/world-map/page.tsx"]:::server
    end
    subgraph "API Routes"
      ChatAPI["app/api/chat/route.ts"]:::api
      AdvSearchAPI["app/api/advanced-search/route.ts"]:::api
      CountriesAPI["app/api/countries/route.ts"]:::api
      CountryCodeAPI["app/api/countries/[countryCode]/route.ts"]:::api
    end
    Middleware["middleware.ts"]:::server
  end

  subgraph "Business Logic Layer (lib)"
    Actions["lib/actions/chat.ts"]:::domain
    AgentsResearch["lib/agents/researcher.ts"]:::domain
    AgentsManual["lib/agents/manual-researcher.ts"]:::domain
    AgentsRelQ["lib/agents/generate-related-questions.ts"]:::domain
    ToolsSearch["lib/tools/search.ts"]:::domain
    ToolsRetrieve["lib/tools/retrieve.ts"]:::domain
    ToolsQuestion["lib/tools/question.ts"]:::domain
    ToolsVideo["lib/tools/video-search.ts"]:::domain
    Stream1["lib/streaming/create-tool-calling-stream.ts"]:::domain
    Stream2["lib/streaming/create-manual-tool-stream.ts"]:::domain
    Stream3["lib/streaming/parse-tool-call.ts"]:::domain
    Stream4["lib/streaming/tool-execution.ts"]:::domain
    Stream5["lib/streaming/handle-stream-finish.ts"]:::domain
    RedisClient["lib/redis.ts"]:::domain
    RedisConfigLib["lib/redis/config.ts"]:::domain
    SchemaSearch["lib/schema/search.tsx"]:::domain
    SchemaRetrieve["lib/schema/retrieve.tsx"]:::domain
    SchemaRelated["lib/schema/related.tsx"]:::domain
    ConfigModels["lib/config/models.ts"]:::domain
    ConfigDefault["lib/config/default-models.json"]:::domain
    Constants["lib/constants/index.ts"]:::domain
  end

  subgraph "Static Data & Assets"
    DataCountries["data/countries.json"]:::storage
    DataGlobe["data/globe.json"]:::storage
    PublicModels["public/config/models.json"]:::storage
  end

  subgraph "Infrastructure & External"
    Upstash["Upstash Redis"]:::storage
    Clerk["Clerk Auth"]:::external
    MapBox["MapBox"]:::external
    AI["AI Providers"]:::external
    SearchProv["Search Providers"]:::external
  end

  %% Flows
  Browser --> UIAppLayout
  UIAppLayout --> UIAppPage
  Browser --> Nav
  Browser --> PageContainer
  UIAppPage --> NextAppDir
  NextAppDir --> SignIn
  NextAppDir --> SignUp
  NextAppDir --> DashHome
  DashHome --> DashAI
  DashHome --> DashMapAnim
  DashHome --> DashWorld

  Browser -->|calls| ChatAPI
  Browser -->|calls| AdvSearchAPI
  Browser -->|calls| CountriesAPI
  Browser -->|calls| CountryCodeAPI
  ChatAPI --> Actions
  AdvSearchAPI --> ToolsSearch
  AdvSearchAPI --> AgentsResearch
  CountriesAPI --> RedisClient
  CountryCodeAPI --> RedisClient

  Actions --> Stream1
  Stream1 --> Stream3
  Stream3 --> Stream4
  Stream4 --> Stream5
  ToolsSearch --> SearchProv
  ToolsRetrieve --> SearchProv
  ToolsQuestion --> AI
  ToolsVideo --> AI

  RedisClient --> RedisConfigLib
  RedisClient --> Upstash
  SchemaSearch --> Upstash
  SchemaRetrieve --> Upstash
  SchemaRelated --> Upstash

  DashMapAnim --> DataCountries
  DashMapAnim --> DataGlobe
  DashMapAnim --> MapBox

  Middleware --> Clerk
  NextAppDir --> Middleware
  ChatAPI --> Middleware
  AdvSearchAPI --> Middleware
  CountriesAPI --> Middleware
  CountryCodeAPI --> Middleware

  %% Click Events
  click UIAppLayout "https://github.com/azekowka/nfactorial/blob/main/app/layout.tsx"
  click UIAppPage "https://github.com/azekowka/nfactorial/blob/main/app/page.tsx"
  click Nav "https://github.com/azekowka/nfactorial/blob/main/components/navbar.tsx"
  click PageContainer "https://github.com/azekowka/nfactorial/blob/main/components/page-container.tsx"
  click NextAppDir "https://github.com/azekowka/nfactorial/tree/main/app/"
  click SignIn "https://github.com/azekowka/nfactorial/blob/main/app/sign-in/[[...sign-in]]/page.tsx"
  click SignUp "https://github.com/azekowka/nfactorial/blob/main/app/sign-up/[[...sign-up]]/page.tsx"
  click DashHome "https://github.com/azekowka/nfactorial/blob/main/app/dashboard/page.tsx"
  click DashAI "https://github.com/azekowka/nfactorial/blob/main/app/dashboard/ai/page.tsx"
  click DashMapAnim "https://github.com/azekowka/nfactorial/blob/main/app/dashboard/map-animate/page.tsx"
  click DashWorld "https://github.com/azekowka/nfactorial/blob/main/app/dashboard/world-map/page.tsx"
  click ChatAPI "https://github.com/azekowka/nfactorial/blob/main/app/api/chat/route.ts"
  click AdvSearchAPI "https://github.com/azekowka/nfactorial/blob/main/app/api/advanced-search/route.ts"
  click CountriesAPI "https://github.com/azekowka/nfactorial/blob/main/app/api/countries/route.ts"
  click CountryCodeAPI "https://github.com/azekowka/nfactorial/blob/main/app/api/countries/[countryCode]/route.ts"
  click Middleware "https://github.com/azekowka/nfactorial/blob/main/middleware.ts"
  click Actions "https://github.com/azekowka/nfactorial/blob/main/lib/actions/chat.ts"
  click AgentsResearch "https://github.com/azekowka/nfactorial/blob/main/lib/agents/researcher.ts"
  click AgentsManual "https://github.com/azekowka/nfactorial/blob/main/lib/agents/manual-researcher.ts"
  click AgentsRelQ "https://github.com/azekowka/nfactorial/blob/main/lib/agents/generate-related-questions.ts"
  click ToolsSearch "https://github.com/azekowka/nfactorial/blob/main/lib/tools/search.ts"
  click ToolsRetrieve "https://github.com/azekowka/nfactorial/blob/main/lib/tools/retrieve.ts"
  click ToolsQuestion "https://github.com/azekowka/nfactorial/blob/main/lib/tools/question.ts"
  click ToolsVideo "https://github.com/azekowka/nfactorial/blob/main/lib/tools/video-search.ts"
  click Stream1 "https://github.com/azekowka/nfactorial/blob/main/lib/streaming/create-tool-calling-stream.ts"
  click Stream2 "https://github.com/azekowka/nfactorial/blob/main/lib/streaming/create-manual-tool-stream.ts"
  click Stream3 "https://github.com/azekowka/nfactorial/blob/main/lib/streaming/parse-tool-call.ts"
  click Stream4 "https://github.com/azekowka/nfactorial/blob/main/lib/streaming/tool-execution.ts"
  click Stream5 "https://github.com/azekowka/nfactorial/blob/main/lib/streaming/handle-stream-finish.ts"
  click RedisClient "https://github.com/azekowka/nfactorial/blob/main/lib/redis.ts"
  click RedisConfigLib "https://github.com/azekowka/nfactorial/blob/main/lib/redis/config.ts"
  click SchemaSearch "https://github.com/azekowka/nfactorial/blob/main/lib/schema/search.tsx"
  click SchemaRetrieve "https://github.com/azekowka/nfactorial/blob/main/lib/schema/retrieve.tsx"
  click SchemaRelated "https://github.com/azekowka/nfactorial/blob/main/lib/schema/related.tsx"
  click ConfigModels "https://github.com/azekowka/nfactorial/blob/main/lib/config/models.ts"
  click ConfigDefault "https://github.com/azekowka/nfactorial/blob/main/lib/config/default-models.json"
  click Constants "https://github.com/azekowka/nfactorial/blob/main/lib/constants/index.ts"
  click DataCountries "https://github.com/azekowka/nfactorial/blob/main/data/countries.json"
  click DataGlobe "https://github.com/azekowka/nfactorial/blob/main/data/globe.json"
  click PublicModels "https://github.com/azekowka/nfactorial/blob/main/public/config/models.json"

  %% Styles
  classDef frontend fill:#E3F2FD,stroke:#1976D2,stroke-width:1px
  classDef server fill:#E8F5E9,stroke:#388E3C,stroke-width:1px
  classDef api fill:#FFF3E0,stroke:#F57C00,stroke-width:1px
  classDef domain fill:#F3E5F5,stroke:#8E24AA,stroke-width:1px
  classDef storage fill:#E0F2F1,stroke:#00796B,stroke-width:1px,stroke-dasharray: 2 2
  classDef external fill:#ECEFF1,stroke:#546E7A,stroke-width:1px,stroke-dasharray: 5 5
```
