Spaces:
Runtime error
Runtime error
File size: 4,992 Bytes
00a4363 2823b28 00a4363 34b0226 00a4363 7299acc 00a4363 94b5741 00a4363 34b0226 00a4363 34b0226 00a4363 34b0226 00a4363 34b0226 00a4363 94b5741 00a4363 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 | # Notestack
Your knowledge, in orbit. Turn any blog, newsletter, site or folder of markdown into a grounded research notebook, audio
overviews, videos and launch kits, all traced back to what the writer actually wrote.
- Design doc: [docs/DESIGN.md](docs/DESIGN.md)
- Foundations task list: [docs/PHASE0.md](docs/PHASE0.md)
## Layout
```
backend/ FastAPI + SQLAlchemy + Alembic, Postgres job queue worker, DSPy (LLM agnostic, Z.ai first)
frontend/ React + Vite + TS: night sky landing, pricing, blog, auth, Mission Control
renderer/ Remotion compositions + render service that uploads to R2 via presigned PUT
docs/ Design doc and task lists
```
## Run locally
```bash
cp .env.example .env # fill LLM_API_KEY (Z.ai), GOOGLE_CLIENT_ID, RESEND_API_KEY
docker compose up --build
```
- App: http://localhost:5173, API: http://localhost:8000/docs, MinIO console: http://localhost:9001
- Local storage is MinIO standing in for R2. Presigned URLs point at `http://minio:9000`, so add
`127.0.0.1 minio` to your hosts file for browser uploads to work locally.
- With `EMAIL_PROVIDER=console`, verification codes print in the `api` logs.
Without Docker (one API process does everything):
```bash
cd backend && python -m venv .venv && .venv/Scripts/pip install -r requirements-dev.txt
alembic upgrade head && uvicorn app.main:app --reload # SQLite at backend/notestack.db
cd frontend && npm install && npm run dev
cd renderer && npm install && npm start # only needed for videos, quote cards, carousels
```
- With `ENV=development` the API runs the job worker in process (`RUN_WORKER_IN_API`), so syncing,
topic mapping, audio and launch kits work without a second terminal. In production run
`python -m app.worker` separately and set `RUN_WORKER_IN_API=false`.
- With no R2 settings, files live on local disk under `backend/.storage` and are served through
signed `/api/storage/local/...` URLs (range requests supported for audio and video seeking).
- Audio needs `ELEVENLABS_API_KEY`; everything text based needs `LLM_API_KEY`.
- Launchpad: Bluesky connects with an app password. X and LinkedIn need developer apps; the
redirect URIs are listed in `.env.example` and on the Launchpad page. Substack Notes has no API,
so those posts (and any post without a connected account) arrive as an email reminder at send time.
## What is in the app
| Menu | Does |
| --- | --- |
| Mission Control | Pre-flight checklist, jobs in flight, sources, notebooks, recent launches, upcoming posts |
| Notebooks | Group posts, chat with cited answers (history kept), summaries, audio overviews, videos, quote cards |
| Sources | Connect feeds (Substack archive included), import one URL, upload md/txt/html/pdf, read posts by line |
| Topic map | LLM tagged topics per post, merged into a constellation; make a notebook from any topic |
| Voice profile | Writing voice built from your posts (editable), host voices, consented voice cloning |
| Video and audio | Audio overviews, 9:16 shorts, 16:9 explainers, 1:1 audiograms, quote cards |
| Launch Kit | Hooks, X thread, LinkedIn, Substack Notes, Bluesky, SEO pack, carousel, quote cards, all editable |
| Launchpad | Calendar and agenda, auto posting to X, LinkedIn and Bluesky, email reminders, tracked links, engagement |
| Archive | Every generated artifact with filters, players, downloads, retry and delete |
| Resurfacing | Evergreen scores and reshare angles for old posts, on this day, straight into a kit or the calendar |
| Settings | Profile, workspace, brand kit, privacy, plan usage meters, connections, sign out everywhere, delete |
## Key choices
| Concern | Where |
| --- | --- |
| Cloudflare R2 storage (keys, presign, uploads) | `backend/app/services/storage.py`, `backend/app/routers/storage.py` |
| Resend email + unsubscribe + campaigns | `backend/app/services/email.py`, `backend/app/worker.py` |
| Google + email code auth, JWT revocation | `backend/app/auth.py`, `backend/app/routers/auth.py` |
| Research over posts as files (no embeddings) | `backend/app/corpus.py`, `backend/app/pipeline/research.py` |
| LLM provider (swap by env) | `backend/app/llm/provider.py`, `.env` `LLM_*` |
| Three plans, billing off | `backend/app/services/plans.py`, `BILLING_ENABLED` |
| Blog posts | `frontend/src/content/blogPosts.ts` (`/blogs`, `/blogs/:slug`) |
| Logo | replace `frontend/public/logo.svg` (white tile, black silhouettes) |
| Sky background | `frontend/src/components/SkyCanvas.tsx` |
## Switching LLM providers
```bash
# Z.ai (default). Cheaper: glm-5.3-flash. Free for dev: glm-4.7-flash
LLM_MODEL=openai/glm-5.3 LLM_API_BASE=https://api.z.ai/api/paas/v4 LLM_REASONING_EFFORT=low
# Anthropic
LLM_MODEL=anthropic/claude-sonnet-5 LLM_API_BASE=
# OpenAI
LLM_MODEL=openai/gpt-5 LLM_API_BASE=
```
## Rules
- No em dashes in any UI, email or generated copy. `npm run check:copy` and
`app/llm/postprocess.py` enforce it.
- Palette is black, `#217cff` and white only.
|