Turn a one-sentence story idea into a complete children's picture-book draft in a single session.
→ Start here: GETTING_STARTED.md — Complete step-by-step guide to get the app running locally in ~10 minutes.
→ Verify your setup: bash verify-setup.sh — Check that all dependencies and configuration are correct.
Rainstorms is an AI-powered children's book creation tool. Give it an idea — "a brave little robot discovers emotions" — and it generates a full story blueprint, named characters with personalities and visual descriptions, page-by-page text, and illustration prompts ready for an artist or image-generation tool. Export everything as a polished PDF in under 30 minutes.
| Home | Idea Lab | Story Blueprint |
|---|---|---|
 |
 |
 |
| Page Builder | Sign In |
|---|---|
 |
 |
| Feature | Description |
|---|---|
| 💡 Idea Lab | Enter your story concept, tone, age range, and page count |
| 📋 Story Blueprint | AI generates title, one-line hook, summary, theme, and a page-by-page outline |
| 🧑🤝🧑 Character Forge | Editable character cards with personality, appearance, and special traits |
| 📖 Page Builder | Generate page text and illustration prompts per page; Improve with one-click modifiers (funnier, cozier, simpler…) |
| 🧠 Story Memory | Consistency tracker keeps characters, settings, and tone coherent across all pages |
| 📤 Export | Download your book as a story PDF, prompts PDF, plain text, or JSON |
| 🚀 Demo Project | Pre-loaded "Captain Blanket and the Midnight Brother" — try the full flow instantly, no account needed |
| 🔐 Auth (optional) | Register/login to save projects; or continue as a guest |
| Layer | Technology |
|---|---|
| Frontend | React Native + Expo (web, iOS, Android) |
| Navigation | Expo Router (file-based) |
| Backend | FastAPI (Python 3.10+) |
| Database | MongoDB (motor async driver) |
| AI (text) | OpenAI GPT-4.1 or Google Gemini 2.0 Flash (your own API key) |
| AI (images) | OpenAI DALL-E 3 (your own OpenAI API key) |
| ReportLab | |
| Auth | JWT (72-hour tokens) + bcrypt |
- Python 3.10+ and pip
- Node 18+ and npm
- MongoDB — local instance (
mongod) or a free MongoDB Atlas cluster - An OpenAI API key (for AI text + image generation) — get one at platform.openai.com/api-keys
- Alternatively, a Google Gemini API key can be used for text generation — get one at aistudio.google.com
git clone https://github.com/Bboy9090/Rainstorms.git
cd Rainstorms
# Backend config
cp backend/.env.example backend/.env
# Edit backend/.env — set MONGO_URL and OPENAI_API_KEY (and optionally GEMINI_API_KEY)
# Frontend config (defaults to localhost:8001 — no changes needed for local dev)
cp frontend/.env.example frontend/.envbash start.shThis script:
- Installs Python deps into
backend/.venv - Installs Node deps in
frontend/ - Starts the FastAPI backend on http://localhost:8001
- Starts the Expo web frontend on http://localhost:8081
Then open http://localhost:8081 in your browser.
Want to try without AI keys? Click "Try Demo Project" on the home screen — the full demo story is pre-loaded from the backend and requires no API calls.
Click to expand
cd backend
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env # fill in MONGO_URL and OPENAI_API_KEY
uvicorn server:app --host 0.0.0.0 --port 8001 --reloadAPI docs available at http://localhost:8001/docs
cd frontend
npm install --legacy-peer-deps
cp .env.example .env # defaults are fine for local dev
npx expo start --web # opens browser automaticallyFor mobile: scan the QR code with Expo Go (iOS/Android).
No account or API key required for the demo path.
- Open http://localhost:8081
- Click "Try Demo Project" → lands on the Story Blueprint
- Read the title, hook, summary, theme, and 10-page outline
- Click "Accept Blueprint" → Character Forge (view Oliver and Baby Max)
- Navigate to Page Builder → page text and illustration prompts are pre-filled
- Click "Export" → download the story PDF
cd frontend
npm install --legacy-peer-deps
npx expo lint # ESLintcd frontend
npx expo export --platform web # outputs to frontend/dist/# Requires a running backend (backend running on localhost:8001)
cd ..
python backend_test.pyAll 22 tests should pass (health, auth, demo project, CRUD, AI generation, export, story memory).
Explore real outputs from Rainstorms to see what the platform can create:
📂 /examples — Sample book exports, illustration examples, and demo media
| Resource | Description |
|---|---|
| 📚 Sample PDFs | Complete storybook exports: Robot Emotions and Captain Blanket |
| 🎨 Illustration Samples | Character reference sheets and page spreads (examples/images) |
| 🎬 Demo GIF | Animated walkthrough of the full creation flow (demo-script.md) |
These examples demonstrate Rainstorms' capabilities from concept to finished book, using the same AI-assisted pipeline available to all users.
Note: Placeholder files indicate where final assets will be placed. See examples/README.md for details on generating these samples.
Rainstorms/
├── backend/
│ ├── server.py # FastAPI app — all endpoints
│ ├── requirements.txt # Python dependencies
│ └── .env.example # Environment variable template
├── frontend/
│ ├── app/ # Expo Router screens (index, idea-lab, blueprint, …)
│ ├── src/
│ │ ├── components/ # Button, Card, Input, Loading, …
│ │ ├── context/ # AuthContext, ProjectContext
│ │ └── utils/ # api.ts, autosave.ts, theme.ts
│ ├── assets/ # Icons, fonts, images
│ └── .env.example # Frontend env template
├── demo/
│ ├── captain_blanket_demo.json # Full structured export (matches API schema)
│ ├── captain_blanket_outline.md # Story outline and character profiles
│ └── captain_blanket_pages.md # All 10 pages with illustration prompts
├── examples/
│ ├── README.md # Sample exports overview
│ ├── demo-script.md # Demo GIF capture guide
│ ├── *.pdf.README.md # PDF placeholders (robot-emotions, captain-blanket)
│ └── images/ # Illustration samples and character reference sheets
├── docs/
│ ├── APP_VISION.md # Product philosophy
│ ├── DEMO_FLOW.md # Captain Blanket walkthrough of the full pipeline
│ ├── DEMO_PROJECT.md # Demo story background and series notes
│ ├── ROADMAP.md # 5-phase product roadmap
│ └── STORY_ENGINE.md # AI generation architecture and API endpoints
├── schemas/
│ ├── story_blueprint.schema.json # Blueprint JSON schema
│ ├── character_profile.schema.json # Character JSON schema
│ └── page_layout.schema.json # Page JSON schema
├── screenshots/ # App store-style screenshots
├── scripts/
│ └── publish-release.sh # Post-merge release script (tag + GitHub release)
├── start.sh # One-click local dev startup
└── backend_test.py # Full API test suite
- No image generation — illustration prompts are created but actual images are not generated; bring your own image tool (Midjourney, DALL·E, etc.)
- Guest sessions are not persisted — work as a guest is stored only in browser memory; closing the tab loses your project unless you're signed in
- API key costs —
OPENAI_API_KEYis used server-side for all AI generation; production deployments should implement per-user key management or rate limiting to control costs - No real-time collaboration — one user edits a project at a time
- PDF formatting — the story PDF uses a basic ReportLab layout; custom fonts and illustrations require additional work
- Mobile app stores — not published to App Store or Google Play in this release; run via Expo Go or the web build
What's in:
- ✅ Full story generation pipeline (idea → blueprint → characters → pages → export)
- ✅ Story Memory consistency tracking
- ✅ "Improve This Page" modifiers (5 styles)
- ✅ PDF and text export
- ✅ Optional user accounts with JWT auth
- ✅ Pre-loaded demo project (no API key needed to explore)
What's out (planned for future versions):
- Series / sequel support
- AI illustration generation
- Voice narration export
- Publishing marketplace
- Real-time collaboration
Ready to deploy Rainstorms to production? Follow the comprehensive deployment guide:
📖 docs/DEPLOYMENT.md — Complete production deployment guide
Recommended Stack:
- Frontend: Vercel (static web hosting)
- Backend: Railway (FastAPI + Python)
- Database: MongoDB Atlas M0 (free tier)
- AI: OpenAI GPT-4.1 + DALL·E 3 (or Google Gemini for text)
Estimated Cost: ~$0–5/month (starter) to ~$40–100/month (at scale)
- Create MongoDB Atlas cluster and copy connection string
- Generate strong
JWT_SECRET - Deploy backend to Railway with environment variables
- Build and deploy frontend to Vercel
- Configure custom domains (optional but recommended)
- Harden CORS and add rate limiting for production
Mobile Apps (Optional): After web launch, publish to iOS/Android using Expo EAS Build — no code rewrite needed.
Stories not loading? See docs/RAILWAY_SETUP.md for Railway + Vercel-specific troubleshooting.
- Fork the repo and create a feature branch
- Follow the existing code style (TypeScript strict mode on frontend, FastAPI patterns on backend)
- Run
npx expo lint(frontend) andpython backend_test.py(backend) before opening a PR - Open a pull request against
mainwith a clear description
MIT © 2024 Rainstorms