Storyloop

Storyloop is a journaling and guidance app for YouTube creators.

It combines:

• a FastAPI backend (SQLite, AI-assisted features, YouTube integration)
• a React frontend (daily workflow, journal editing, activity feed)

The goal is simple: help creators connect what they are trying, what happened, and what to do next.

See:
https://youtu.be/lg4f5IGi-zo https://youtu.be/3Q95Rh8sRic

Features

📝 Smart journals — AI-powered entries that update themselves on a schedule, pulling context from your channel and past notes

💬 Loopie, your creative partner — a chat assistant that knows your journal, your videos, and can edit entries for you

📺 YouTube activity feed — your uploads, journals, and daily tasks in one chronological view

🎙️ Voice-to-journal — dictate entries and let the app format them into structured notes

🏠 Local model support — run everything through Ollama for full privacy, or use OpenAI — your choice

Project Layout

• backend/ FastAPI app, services, persistence, tests
• frontend/ React app, API hooks, components, tests
• scripts/ developer utilities
• thinking/ architecture notes, design docs, and product exploration

The thinking/ folder is for deeper context. Start with this README for setup, then use thinking/ when you want implementation rationale and planning detail.

Quick Start

Prerequisites

• Python 3.11
• Node.js 18+
• uv
• pnpm

1. Clone and install dependencies

cd backend && uv sync
cd ../frontend && pnpm install
cd ..

2. Configure environment

cp .env.example .env

Set values in .env as needed.

3. Run in development

make dev

Default local URLs:

• Frontend: http://127.0.0.1:5173
• Backend API: http://127.0.0.1:8001

Core Environment Variables

See .env.example for the full list.

• YOUTUBE_API_KEY: required when demo mode is off
• YOUTUBE_DEMO_MODE=true: run YouTube flows from fixtures
• DATABASE_URL: primary SQLite database
• DEMO_DATABASE_URL: demo-mode SQLite database
• CORS_ORIGINS: comma-separated frontend origins

Model provider settings are configured in-app under Settings → General → Model settings. OpenAI key setup is required for dictation.

Common Commands

make dev             # frontend + backend (hot reload)
make backend         # backend only
make prod            # production-like local run
make build           # frontend production build
make lint            # backend + frontend lint
make test            # backend + frontend tests
make test-backend    # backend tests only
make test-frontend   # frontend tests only

Code Quality

The good-code-rubric.md describes the code quality standards used in this project. It was introduced partway through development, so earlier code may not fully conform. New contributions should follow the rubric.

Open Source Governance

• LICENSE (MIT)
• Code of Conduct
• Contributing Guide
• Dependency and License Policy
• Third-Party Notices
• GitHub Security Setup Checklist