Skip to content

Latest commit

 

History

History
702 lines (531 loc) · 31.8 KB

README.md

File metadata and controls

702 lines (531 loc) · 31.8 KB

GroqTales Logo
GroqTales

AI-Powered Web3 Storytelling Platform

Create, share, and own AI-generated stories and comics as NFTs on the Monad blockchain.

Open Issues Open PRs License Website Contact Us Discord

SWOC'26 OSGC'26 ECWOC'26 GSSOC'25 FOSS Hack HACKOCTOBER Indie Hub Indie Developers Society Open Source Community Investment Partners

Built by Indie Hub ✨

Star on GitHub
⭐ If you like this project, please consider giving it a star! ⭐

Animated Divider

📋 Table of Contents

What is GroqTales?

GroqTales is an open-source, AI-powered Web3 storytelling platform. Writers and artists can generate immersive narratives or comic-style stories using AI (Google Gemini as the chairman model + Groq for narrow tasks), then mint and trade them as NFTs on Ethereum Mainnet via Alchemy. With a focus on ownership, authenticity, and community, GroqTales bridges the world of creative writing, generative AI, and decentralized technology.

Features

  • AI-Driven Story & Comic Generation Use Groq AI to generate stories or comic panel outlines by specifying title, genre, setting, characters, and themes. Both text and comic formats are supported.
  • Professional Story Creation UI: Redesigned creation for Text, Comic, and AI-generated stories with professional canvas-based interfaces to visualize story structure.
  • Interactive Story Canvas: A reusable SVG-based canvas supports drag-and-drop node positioning with grid snapping, zoom controls, and real-time info panel. It includes auto-saving to local storage.
  • Extensive Story Customization (70+ Parameters): Fine-tune every aspect of your story with a powerful Parameter Management System. Includes 70+ parameters across 10 categories, intelligence-level presets, and an advanced UI with search and filtering.
  • Guided Onboarding Tours: Interactive guided tours for each creation mode to help new users get started quickly.
  • Clickable Gallery → Story Detail Pages Browse the gallery, click any story card to open a dedicated story page with a full book-like reading experience.
  • Book-Style Reader with TTS Audiobook Each story page features a Kindle-style book view with chapter navigation, serif typography, and an integrated Sarvam AI Bulbul v3 text-to-speech audiobook player. Choose speaker, language (English default), and playback speed.
  • Reddit-Style Story Engagement Upvote/downvote stories, post and read comments (with avatars and timestamps), and bookmark stories to your "Saved Creations" collection.
  • NFT Minting on Ethereum Mainnet Mint your stories as NFTs on Ethereum Mainnet via Alchemy with a server-side platform signer. Each NFT proves authenticity, ownership, and collectibility.
  • Community Gallery Publish your stories publicly, browse the gallery, and interact with other creators. Stories can be shared freely or as NFTs.
  • Wallet Integration Connect with MetaMask or WalletConnect v2 (QR code modal) for secure publishing and minting. Signature-based authentication with backend token issuance.
  • Supabase Storage Cloud storage for avatars, story covers, comic panels, and NFT metadata with Row Level Security policies.
  • Analytics Warehouse Supabase S3/Iceberg analytics integration with pre-built engagement summary views for tracking votes, comments, and saves per story.
  • Real-Time Story Streaming Watch your story unfold in real-time as Groq AI generates each segment.
  • Mobile-Friendly & Responsive UI Built with modern web technologies for a seamless experience on any device.
  • Docker Support Multi-stage Dockerfile with Redis caching + Docker Compose for local development.
  • Extensible & Open Source Modular codebase with clear separation of frontend, backend, and smart contract logic. Contributions are welcome!

Tech Stack

  • Frontend: Next.js, React, TailwindCSS, shadcn/ui
  • Backend: Node.js, Express.js API (Render), Cloudflare Workers
  • AI: Google Gemini (chairman model for story generation), Groq LPU (narrow tasks — parameter validation, classification, outlines), Sarvam AI (Text-to-Speech)
  • Blockchain: Ethereum Mainnet via Alchemy, Solidity Smart Contracts, WalletConnect, MetaMask
  • Database & Storage: Supabase (PostgreSQL) with Row Level Security, Supabase Storage (avatars, story-covers, comic-panels, nft-metadata), IPFS via Pinata
  • Hosting: Cloudflare Pages (frontend), Render (backend API)
  • Monitoring: UptimeRobot Status Page

Quick Start

git clone https://github.com/IndieHub25/GroqTales
cd GroqTales
npm install
cp .env.example .env.local
# Fill in GROQ_API_KEY, GEMINI_API_KEY, Supabase keys, SARVAM_API_KEY, and wallet config
npm run dev

Docker (Optional)

cp .env.example .env.local
# Fill in all environment variables
docker compose up --build
  1. Visit http://localhost:3000
  2. Connect your wallet (optional; required for minting/publishing)
  3. Generate your story → Publish or Mint as NFT

See the Wiki for configuration, environment variables, and deployment details.

API Access & Monitoring

Base API URL (Production): https://groqtales-backend-api.onrender.com

Health Checks

For continuous uptime monitoring (e.g., UptimeRobot, Render Health Checks, Datadog), always point to the dedicated, robust liveness probe:

  • Liveness Probe: GET /healthz — Returns an instant 200 OK bypassing all middleware, rate limiters, and external database latency. Use this for raw "is the server running?" checks.
  • Deep Diagnostics: GET /api/health — Returns extremely detailed server diagnostics including Supabase connectivity, process memory usage, and uptime. (Subject to rate limits).
  • Status Page: https://stats.uptimerobot.com/PUi1I3YaBH — Public uptime monitoring dashboard.

🛠️ Environment Configuration

To run this project locally, you must set up your environment variables. Create a file named .env.local in the root directory and populate it with the following keys:

.env.local Setup

Variable Requirement Description
GROQ_API_KEY Required Powers the AI story generation engine via Groq LPU.
NEXT_PUBLIC_SUPABASE_URL Required Your Supabase project URL for database and authentication.
NEXT_PUBLIC_SUPABASE_ANON_KEY Required Supabase anonymous/public API key for client-side access.
ALCHEMY_ETH_MAINNET_HTTP_URL Required The Alchemy RPC endpoint for interacting with Ethereum Mainnet.
NEXT_PUBLIC_API_URL Required Backend API URL (e.g., https://groqtales-backend-api.onrender.com).
NEXT_PUBLIC_UNSPLASH_API_KEY Optional API key used for fetching high-quality cover images for stories.
NEXT_PUBLIC_CONTRACT_ADDR Required The smart contract address for the deployed NFT collection.
NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID Required WalletConnect project ID for wallet integration.
UPSTASH_REDIS_REST_URL Optional URL for Upstash Redis (used for AI cache & rate limiting).
UPSTASH_REDIS_REST_TOKEN Optional Token for Upstash Redis REST API.
REDIS_URL Optional Alternate Redis connection string (used by notifications/cache if not using Upstash).
MONGODB_URI Optional MongoDB connection string (required for local Mongo-based features).
NEXT_PUBLIC_URL Optional Public base URL of the frontend (used when constructing links in emails, etc.).

🔑 How to get these keys:

  1. Groq API: Generate a key at Groq Cloud Console.
  2. Supabase: Create a free project at Supabase and copy the project URL and anon key from Settings → API.
  3. Ethereum RPC: Create a free project at Alchemy to get your ALCHEMY_ETH_MAINNET_HTTP_URL.
  4. Unsplash: Register an application on the Unsplash Developer Portal.
  5. WalletConnect: Create a project at WalletConnect Cloud.

Warning

Never commit your .env.local file to version control. Ensure it is listed in your .gitignore to prevent leaking sensitive API keys.

🐳 Docker

GroqTales ships with a production-ready Docker setup. The docker-compose.yml spins up all required services in one command.

Services

Service Image Port(s) Purpose
server Built from Dockerfile (Node 22) 3000, 3001 Next.js frontend + Express backend

| anvil | ghcr.io/foundry-rs/foundry:v1.0.0 | 8545 | Local Ethereum-compatible dev chain |

Quick Start

# Build & launch everything (Anvil, app)
docker compose up --build

# Run in detached mode
docker compose up --build -d

# View logs
docker compose logs -f server

# Stop all services
docker compose down

Your application will be available at http://localhost:3000 (frontend) and http://localhost:3001 (backend API).

Building for Cloud Deployment

# Build the image
docker build -t groqtales .

# Cross-platform build (e.g., Mac M-series → amd64 cloud)
docker build --platform=linux/amd64 -t groqtales .

# Push to your registry
docker push myregistry.com/groqtales

Environment Variables

Docker Compose sets these automatically. Override them in a .env file or in docker-compose.override.yml:

Variable Default (Docker)
NEXT_PUBLIC_SUPABASE_URL http://supabase:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY your-anon-key
ALCHEMY_ETH_MAINNET_HTTP_URL https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY
NODE_ENV development

Tip

For production, set NODE_ENV=production and add your GROQ_API_KEY, ALCHEMY_ETH_MAINNET_HTTP_URL, and other secrets via environment variables — never bake them into the image.

References

📜 Smart Contracts

GroqTales utilizes Solidity-based smart contracts for NFT minting and ownership management. We prefer Hardhat for local development, compilation, and testing.

🛠️ Contract Workflow

  • Contract Location: /contracts/
  • Compile: npx hardhat compile
  • Local Test: npx hardhat test
  • Network: Monad Testnet (ChainID: 10143)

[!WARNING] Safety Disclaimer: GroqTales currently operates exclusively on the Monad Testnet. Do not send real funds (ETH or Mainnet MON) to these contract addresses. Always use a dedicated developer/faucet-funded wallet for testing.

🏗️ System Architecture

GroqTales follows a decoupled architecture ensuring high-speed AI inference and decentralized ownership.

graph TD
    A[User Interface - Next.js] -->|Prompt with 70+ Params| B[Backend API - Node.js]
    B -->|Story Generation| C[Google Gemini Chairman]
    B -->|Validation & Outlines| D[Groq LPU Engine]
    C -->|Structured JSON Story| B
    D -->|Classification Data| B
    B -->|Metadata & Auth| E[Supabase PostgreSQL]
    B -->|Media Files| F[Supabase Storage]
    B -->|NFT Metadata| G[IPFS via Pinata]
    A -->|MetaMask / WalletConnect| H[Ethereum Mainnet via Alchemy]
    H --- I[Smart Contracts - Solidity]
Loading

For Developers

  • Folder Structure:

    • /app – Next.js application (pages, UI, routes)
    • /components – Reusable React components
    • /contracts – Solidity smart contracts for NFT minting
    • /lib – Utility functions and API integrations
    • /public – Static assets
    • /test and /tests – Test scripts and sample data
    • /scripts – Automation and deployment scripts

  • Environment Variables:

    • GROQ_API_KEY – Your Groq AI API key
    • NEXT_PUBLIC_UNSPLASH_API_KEY – (Optional) for placeholder visuals
    • ALCHEMY_ETH_MAINNET_HTTP_URL – Alchemy Ethereum Mainnet RPC endpoint

  • Smart Contract Deployment:

    • Contracts are written in Solidity and can be deployed to Monad Testnet/Mainnet.
    • See /contracts and /scripts for deployment instructions.

  • Extending AI Models:

    • AI logic is modular—add support for new models or prompt types in /lib and /components.

  • Testing:

    • Frontend: Use Jest/React Testing Library.
    • Smart Contracts: Use Hardhat/Foundry for Solidity tests.

  • Contributions:

📁 Program Structure


GroqTales/
│
├── GroqTales/                # Core domain / main feature-specific logic
│
├── app/                      # Next.js App Router (pages, layouts, routes)
├── components/               # Reusable UI components
├── config/                   # App-wide configuration files
├── deployment/               # Deployment configurations
├── docs/                     # Documentation and guides
├── hooks/                    # Custom React hooks
├── lib/                      # Shared libraries and helper logic
├── models/                   # Data models and schemas
├── path/to/your/             # Placeholder / experimental structure
├── public/                   # Static assets (images, icons, fonts)
├── scripts/                  # Utility and automation scripts
├── server/                   # Backend/server-side logic
├── smart_contracts/          # Blockchain smart contracts
├── src/                      # Core application source code
├── tests/                    # Test cases and testing utilities
├── types/                    # TypeScript type definitions
├── utils/                    # Utility/helper functions
├── wiki/                     # Wiki-related content
├── workers/                  # Background workers / async jobs
│
├── .env.example              # Sample environment variables
├── .eslintrc.js              # ESLint configuration
├── .gitignore                # Git ignored files
├── .hintrc                   # Web hinting configuration
├── .nvmrc                    # Node.js version specification
├── .prettierignore           # Files ignored by Prettier
├── .prettierrc               # Prettier formatting rules
│
├── CHANGELOG.md              # Project change history
├── CODE_OF_CONDUCT.md        # Community code of conduct
├── CONTRIBUTING.md           # Contribution guidelines
├── COOKIE_POLICY.md          # Cookie usage policy
├── LICENSE                   # License information
├── README.md                 # Project overview and instructions
├── SECURITY.md               # Security policy
├── TERMS_OF_SERVICE.md       # Terms of service
├── VERSION                   # Project version file
│
├── build_log.txt             # Build logs
├── foundry.toml              # Foundry configuration (smart contracts)
├── lighthouserc.json         # Lighthouse performance config
├── wrangler.toml             # Cloudflare Pages/Workers configuration
└── MIGRATION-TO-CLOUDFLARE.md # Cloudflare migration guide

📸 Screenshots

🏠 Landing Page

Displays the GroqTales homepage introducing AI-powered storytelling with options to create, mint, and share stories as NFTs.

Screenshot 2026-01-29 182943

❓ Why GroqTales

Highlights the core features of GroqTales including AI generation, blockchain ownership, and creator community.

Screenshot 2026-01-29 183000

🎭 Story Genres

Presents available storytelling genres such as Science Fiction, Fantasy, and Romance with key themes and elements.

Screenshot 2026-01-29 183112

👥 Community Feed

Showcases the community feed where creators share stories, interact, and discover trending content.

Screenshot 2026-01-29 183127

🛒 NFT Marketplace

Illustrates the NFT marketplace for browsing and uploading comic and text-based story NFTs.

Screenshot 2026-01-29 183149

🤝 Contributing

📌 New contributors: Please read our CONTRIBUTING.md to understand issue labels, templates, and workflows. GroqTales is community-powered! We welcome all contributions—whether you're a developer, designer, writer, or blockchain enthusiast.

How You Can Help:

  • Tackle issues labeled good first issue (great for newcomers)
  • Enhance story-generation logic, outlines, or UI design
  • Add support for new AI models or blockchains
  • Improve UX (dark mode, mobile layout, galleries)
  • Optimize NFT metadata or IPFS workflows
  • Write or improve documentation and tests

What’s in It for You:

  • Build your open-source portfolio
  • Feature your work in the contributors section
  • Community recognition and GitHub Sponsors eligibility

See CONTRIBUTING.md for guidelines.

🎨 Spline 3D Guide

For detailed information on how to work with 3D models, performance rules, and our model protection policy, please refer to the Spline 3D Contributor Guide.

Roadmap

  • AI visuals: Integrate Stable Diffusion/DALL·E for comic panels [Phase 2]
  • Multilingual story generation [Phase 4]
  • Native marketplace for story NFTs [Phase 1]
  • Enhanced wallet security & decentralized data storage [Phase 1]
  • Mobile app support [Phase 5]
  • More blockchain integrations [Open for Discussions on Ideas]

Contributors

We value every contribution! Please read our CONTRIBUTORS.md file before making your first contribution to understand our guidelines and recognition process.

Project Contributors

Contributors

Thanks to these amazing people for making GroqTales better!

Documentation & Architecture

Core Documentation

  • Architecture Overview: ARCHITECTURE.md - Comprehensive system design and technical architecture
  • AI Prompt Engineering: Wiki/AI-Prompt-Engineering - AI system prompt parameter reference
  • Pipelines & Automation: PIPELINES.md - Comprehensive guide for the Cloudflare AI ML rankings, SEO RAG loops, and Admin queues
  • Spline 3D Guide: SPLINE_GUIDE.md - Essential guide for 3D model contributions and protection policy
  • Project Wiki: GitHub Wiki - Detailed guides and documentation
  • API Documentation: Wiki/API - Backend API reference
  • Smart Contracts: Wiki/Blockchain - Contract documentation

System Architecture

VedaScript Engine Parameters

The VedaScript Engine exposes 71 tunable parameters across 10 categories, defined in lib/ai-story-parameters.ts. Each parameter has a UI control type (slider, select, toggle, multiselect, text, or textarea), a default value, and contextual help text.

Character Development (11 parameters)

Key Type Default Description
characterCount slider 3 Number of main characters (1–10)
characterDepth slider 5 How deeply characters are developed (1–10)
protagonistArchetype select hero Main character archetype (hero, antihero, reluctant-hero, byronic, everyman)
antagonistPresence slider 5 How prominent the antagonist is (0–10)
sideCharacterCount slider 2 Number of side characters (0–8)
characterDiversity slider 5 Diversity of character backgrounds (1–10)
relationshipComplexity slider 5 Complexity of interpersonal relationships (1–10)
characterMotivationClarity slider 7 How clear character motivations are (1–10)
characterVoiceDistinctness slider 5 Distinctness of each character's voice (1–10)
characterFlaws slider 5 How prominent character flaws are (0–10)
characterGrowth slider 5 Extent of character arcs (0–10)

Plot Structure (12 parameters)

Key Type Default Description
plotComplexity slider 5 Overall plot complexity (1–10)
pacingSpeed slider 5 Story pacing speed (1=slow, 10=breakneck)
cliffhangerFrequency slider 3 How often cliffhangers appear (0–10)
plotStructureType select three-act Story structure (three-act, hero-journey, in-medias-res, circular, nonlinear)
twistCount slider 1 Number of major plot twists (0–5)
conflictType select person-vs-person Primary conflict type
resolutionType select resolved Ending resolution style
flashbackUsage slider 2 How frequently flashbacks are used (0–10)
foreshadowingLevel slider 4 Intensity of foreshadowing (0–10)
chapterRole select advance-plot Primary purpose of each chapter
hookStrength slider 7 Strength of opening hook per chapter (1–10)
endingType select satisfying Overall ending type

Worldbuilding (9 parameters)

Key Type Default Description
settingDetail slider 5 How much world detail to include (1–10)
settingType select urban Primary setting type
worldMagicSystem select none Magic/power system type
technologyLevel select modern Technology level
worldHistoryDepth slider 3 Depth of world history/lore (0–10)
politicsComplexity slider 2 Political complexities (0–10)
economicSystem select market Economic system type
culturalDiversity slider 5 Cultural diversity in the world (1–10)
atmosphere select neutral General atmosphere of the world

Tone & Style (8 parameters)

Key Type Default Description
narrativeVoice select third-limited Point-of-view voice style
proseStyle select literary Writing style
dialogueLevel slider 5 Proportion of dialogue vs narration (0–10)
dialogueNaturalism slider 6 How natural/realistic dialogue sounds (1–10)
humorLevel slider 3 Amount of humor in the story (0–10)
humorStyle select witty Style of humor when used
darknessLevel slider 4 How dark/grim the tone is (0–10)
sentimentTone select balanced Overall emotional tone

Technical Parameters (7 parameters)

Key Type Default Description
targetWordCount slider 3000 Target word count (500–50,000)
readingLevel select adult Target reading level
pointOfView select third-person Narrative POV
verbTense select past Primary verb tense
chapterStructure select traditional Chapter layout structure
descriptionIntensity slider 5 Density of descriptive passages (1–10)
narrativeTimeSpan select weeks Time covered by the story

Thematic Elements (5 parameters)

Key Type Default Description
themeDepth slider 5 How deeply themes are explored (1–10)
themeSubtlety slider 5 How subtly themes are woven in (1–10)
symbolismLevel slider 3 Amount of symbolism (0–10)
metaphorDensity slider 3 Density of metaphors (0–10)
moralComplexity slider 5 Moral ambiguity in the story (1–10)

Sensory & Immersion (5 parameters)

Key Type Default Description
sensoryDetail slider 5 Sensory descriptions (sight, sound, etc.) (1–10)
actionDescription slider 5 Detail level of action scenes (1–10)
emotionalDepth slider 5 Emotional intensity (1–10)
tensionCurve select rising Tension progression pattern
immersionLevel slider 6 Overall immersion quality (1–10)

Audience (4 parameters)

Key Type Default Description
ageRating select teen Target age rating
contentWarnings multiselect [] Content warnings to flag
genderRepresentation slider 5 Gender balance in cast (1–10)
culturalSensitivity slider 7 Level of cultural sensitivity (1–10)

Advanced Options (6 parameters)

Key Type Default Description
creativityLevel slider 5 AI creative freedom (1=conservative, 10=wild)
coherenceStrictness slider 7 How strictly coherence is enforced (1–10)
randomizationSeed text — Seed for reproducible generation
modelTemperature slider 0.7 LLM temperature (0.0–2.0, step 0.1)
detailLevel slider 5 Overall detail density (1–10)
guardrailsStrictness slider 8 Safety guardrail level (1–10)

Special Effects (4 parameters)

Key Type Default Description
specialNarrativeDevice select none Special storytelling device (unreliable narrator, epistolary, etc.)
easterEggs toggle false Include hidden references
crossReferences toggle false Reference other stories/works
genreBlending slider 0 How much to blend secondary genres (0–10)

Source file: lib/ai-story-parameters.ts — full parameter definitions with Zod validation, preset configurations, and search utilities.

Development Resources

Resources

License

Released under the MIT License.

Security

For vulnerabilities or security-related issues, please refer to SECURITY.md.

Note

GroqTales currently operates on Monad Testnet for NFT minting. Mainnet support coming soon—stay tuned!

Support the project by giving us a follow & a Star ⭐️ and share it with others.