GroqTales

AI-Powered Web3 Storytelling Platform

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

Built by Indie Hub ✨

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

📋 Table of Contents

What is GroqTales?
Features
Tech Stack
Quick Start
🛠️ Environment Configuration
🐳 Docker
📜 Smart Contracts
🏗️ System Architecture
For Developers
🤝 Contributing
🎨 Spline 3D Guide
Roadmap
Contributors
Documentation & Architecture
Resources
License
Security

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 Groq AI, then mint and trade them as NFTs on the Monad blockchain. 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.
Extensive Story Customization (70+ Parameters) Fine-tune every aspect of your story with comprehensive customization across 9 categories:
- Characters: Name, count, traits, age, background, protagonist type
- Plot & Structure: Type, conflict, arc, pacing, ending, plot twists
- Setting & World: Time period, location, world-building depth, atmosphere
- Writing Style & Tone: Voice, tone, style, reading level, mood, dialogue percentage, description detail
- Themes & Messages: Primary/secondary themes, moral complexity, social commentary
- Content Controls: Violence, romance, language levels, mature content warnings
- Advanced Options: Chapters, foreshadowing, symbolism, multiple POVs
- Inspiration & References: Similar works, inspired by, tropes to avoid/include
- Technical Parameters: AI creativity slider, model selection
NFT Minting on Monad Blockchain Seamlessly mint your stories as NFTs on Monad (Testnet live, Mainnet coming soon). 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.
Progressive Disclosure UI Clean, accordion-based interface with 9 collapsible sections. Keeps simple tasks simple while offering advanced options when needed. Only prompt is required—everything else is optional!
Wallet Integration Connect with MetaMask, WalletConnect, or Ledger for secure publishing and minting. Wallet is required for NFT actions.
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.
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: Groq API (story generation with 70+ configurable parameters), Unsplash API (optional visuals)
Blockchain: Monad SDK, Solidity Smart Contracts
Database: Supabase (PostgreSQL) with Row Level Security
Hosting: Cloudflare Pages (frontend), Render (backend API)

Quick Start

git clone https://github.com/IndieHub25/GroqTales
cd GroqTales
npm install
cp .env.example .env.local
# Add GROQ_API_KEY, UNSPLASH key, Monad network if needed
npm run dev

Visit http://localhost:3000
Connect your wallet (optional; required for minting/publishing)
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).

🛠️ 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.
`MONAD_RPC_URL`	Required	The RPC endpoint for interacting with the Monad Testnet.
`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.

🔑 How to get these keys:

Groq API: Generate a key at Groq Cloud Console.
Supabase: Create a free project at Supabase and copy the project URL and anon key from Settings → API.
Monad RPC: Use the official Monad Testnet docs to find the latest RPC URL.
Unsplash: Register an application on the Unsplash Developer Portal.
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

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`
`NEXT_PUBLIC_RPC_URL`	`http://anvil:8545`
`NODE_ENV`	`development`

Tip

For production, set NODE_ENV=production and add your GROQ_API_KEY, MONAD_RPC_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 -->|Inference Request| C[Groq AI LPU Engine]
    C -->|Structured JSON Story| B
    B -->|Metadata| D[Supabase PostgreSQL]
    B -->|IPFS Upload| E[Story/Image Data]
    A -->|Mint NFT| F[Monad Testnet Blockchain]
    F --- G[Smart Contracts - Solidity]

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
- MONAD_RPC_URL – Monad blockchain 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:
- Issues are tagged by difficulty, area, and technology for easy onboarding.
- Please read CONTRIBUTING.md and CONTRIBUTORS.md before submitting PRs.

📁 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.

❓ Why GroqTales

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

🎭 Story Genres

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

👥 Community Feed

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

🛒 NFT Marketplace

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

🤝 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

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

Frontend Architecture: ARCHITECTURE.md#frontend - Next.js application structure
Backend Architecture: ARCHITECTURE.md#backend - API and service design
Blockchain Integration: ARCHITECTURE.md#blockchain - Web3 and smart contract integration
AI Integration: ARCHITECTURE.md#ai - Groq AI implementation
System Diagrams: ARCHITECTURE.md#diagrams - Mermaid flowcharts and architecture diagrams

Development Resources

Setup Guide: Wiki/Development-Setup
Contributing: CONTRIBUTING.md - How to contribute to the project
Code of Conduct: CODE_OF_CONDUCT.md - Community guidelines
Security Policy: SECURITY.md - Security practices and vulnerability reporting

Resources

Website: groqtales.xyz
Docs: Wiki
Community Hub: GitHub Discussions
Discord Support: Join our Discord

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!

Active At

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

Name		Name	Last commit message	Last commit date
Latest commit History 783 Commits
.github		.github
.vscode		.vscode
__tests__/bugfix		__tests__/bugfix
app		app
cf-worker		cf-worker
components		components
config		config
docs		docs
e2e		e2e
hooks		hooks
lib		lib
models		models
public		public
scripts		scripts
server		server
smart_contracts		smart_contracts
src		src
supabase		supabase
tests		tests
types		types
utils		utils
wiki		wiki
workers		workers
.dockerignore		.dockerignore
.env.docker		.env.docker
.env.example		.env.example
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.hintrc		.hintrc
.npmrc		.npmrc
.nvmrc		.nvmrc
.prettierignore		.prettierignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
COOKIE_POLICY.md		COOKIE_POLICY.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
TERMS_OF_SERVICE.md		TERMS_OF_SERVICE.md
TESTING_DOUBLE_MINT_PREVENTION.md		TESTING_DOUBLE_MINT_PREVENTION.md
VERSION		VERSION
components.json		components.json
docker-compose.yml		docker-compose.yml
foundry.toml		foundry.toml
jest.config.js		jest.config.js
jest.setup.js		jest.setup.js
lighthouserc.json		lighthouserc.json
next.config.js		next.config.js
package-lock.json		package-lock.json
package.json		package.json
playwright.config.ts		playwright.config.ts
postcss.config.js		postcss.config.js
render.yaml		render.yaml
tailwind.config.js		tailwind.config.js
tsconfig.json		tsconfig.json
wrangler.toml		wrangler.toml

Folders and files

Latest commit

History

Repository files navigation

GroqTales

📋 Table of Contents

What is GroqTales?

Features

Tech Stack

Quick Start

API Access & Monitoring

Health Checks

🛠️ Environment Configuration

.env.local Setup

🔑 How to get these keys:

🐳 Docker

Services

Quick Start

Building for Cloud Deployment

Environment Variables

References

📜 Smart Contracts

🛠️ Contract Workflow

🏗️ System Architecture

For Developers

📁 Program Structure

📸 Screenshots

🏠 Landing Page

❓ Why GroqTales

🎭 Story Genres

👥 Community Feed

🛒 NFT Marketplace

🤝 Contributing

🎨 Spline 3D Guide

Roadmap

Contributors

Project Contributors

Documentation & Architecture

Core Documentation

System Architecture

Development Resources

Resources

License

Security

Note

Active At

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

`.env.local` Setup

Packages