A multi-tenant knowledge graph explorer for deep research. Astrapai turns interconnected notes into interactive visualizations -- force-directed graphs, semantic-zoom timelines, and documentary storyboards -- all backed by Supabase with Row Level Security on every table.
Most note-taking tools give you a flat list or a folder tree. Astrapai is different: it treats your research as a graph of relationships between people, projects, concepts, events, and media. You see how everything connects -- visually -- and navigate by clicking through the web of links, not by scrolling through files.
Astrapai is a Next.js 16 app with a Supabase backend. Every route is auth-gated, every query is user-scoped via RLS, and the dashboard renders server-side for instant first paint. You interact with your knowledge graph through four main views:
Force-directed D3 visualization of all nodes and their relationships. Drag nodes, zoom in, and click to navigate.
Individual node pages with markdown content, wikilink resolution, connection maps, and a mini-graph showing direct relationships.
Chronological visualization with semantic zoom -- density clusters at low zoom, individual pills at high zoom. Click an orb to zoom into that time period.
Documentary narrative view with tension arcs and screenplay formatting. Requires RSP.
Wikilinks -- Node content supports [[Any Title]] syntax that automatically resolves to clickable links between nodes. Content is ingested via the RSP pipeline -- Astrapai renders and navigates the resulting link graph.
8 Node Types -- Projects, people, concepts, tools, skills, workflows, events, and media. Each type has its own color in the graph and timeline views, making it easy to see the shape of your research at a glance.
Semantic Zoom Timelines -- Timelines aren't just a list of dates. At low zoom you see density clusters showing where activity is concentrated. Zoom in and individual events appear as labeled pills with collision-avoidant lane stacking. Click a density orb to zoom into that time period.
Multi-Tenant by Default -- Every table uses Row Level Security scoped to auth.uid(). There are no admin backdoors, no shared data, no query that can leak across users. Mutations run exclusively through Server Actions -- no client-side writes.
Visual Exports -- PNG snapshots for the graph, timeline, and storyboard views, plus treatment PDF export with research appendix.
| Requirement | Notes |
|---|---|
| Node.js 18+ | Runtime for Next.js |
| npm | Ships with Node.js |
| Supabase project | Free tier works. Create one at database.new |
| Vercel account (optional) | For production deployment. Local dev works without it |
| Supabase CLI (optional) | For local development with supabase start |
git clone https://github.com/OSideMedia/Astrapai.git
cd Astrapai
npm install
cp .env.example .env.local # fill in Supabase credentials
npx supabase db push # run all 10 migrations
npm run dev # open http://localhost:3000For the full walkthrough including local Supabase setup, migration details, and troubleshooting, see SETUP.md.
| Feature | Description |
|---|---|
| Knowledge Graph | Interactive D3 force-directed graph of nodes and edges with drag, zoom, and click-to-navigate |
| Node Detail | Markdown rendering with wikilink resolution, connection maps, sources, snapshots, and metadata |
| Timelines | Chronological D3 visualization with 2-level semantic zoom, density orbs, greedy lane stacking, and PNG export |
| Storyboard | Tension arc chart, screenplay-formatted ScriptFlow, Writer's Focus mode (requires RSP) |
| Dashboard | Server-rendered overview with node counts, recent activity, and type distribution |
| Multi-Tenant Auth | Supabase Auth (email/password) with RLS on all tables |
| Quick Switcher | Cmd+K to search and jump to any node instantly |
| Treatment PDF | Professional export with screenplay formatting, research appendix, and source citations |
| Resizable Panels | Three-column layout with draggable dividers and persistent widths |
| Layer | Technology |
|---|---|
| Framework | Next.js 16 (App Router) + React 19 |
| Language | TypeScript 6 |
| Database | Supabase (Postgres + Auth + RLS) |
| Visualization | D3.js 7.9 (force simulation, timelines, tension arcs) |
| Styling | Tailwind CSS 4 |
| Markdown | react-markdown + remark-gfm |
| Icons | Lucide React |
| Testing | Vitest |
| CI | GitHub Actions (lint, typecheck, test, build) |
| Deployment | Vercel |
src/
app/ Next.js App Router
├── page.tsx Dashboard (Server Component)
├── graph/ Force-directed graph view
├── nodes/[id]/ Node detail pages
├── timelines/ Timeline list, create, view, edit
├── storyboard/ RSP narrative view
├── settings/ User account settings
└── login/ Auth pages
components/ React Client Components
├── Sidebar.tsx Node list with search and filtering
├── TopNav.tsx Navigation bar with UserMenu
├── NodeDetail.tsx Full node view with markdown + connections
├── MiniGraph.tsx D3 mini-graph per node
├── ResizablePanels.tsx Three-column draggable layout
├── DashboardContent.tsx Dashboard cards and activity feed
├── MarkdownContent.tsx Markdown renderer with wikilink support
├── QuickSwitcher.tsx Cmd+K search overlay
├── D3TimelineEngine.tsx Timeline visualization engine
└── storyboard/ TensionArc, ScriptFlow, NodePicker
lib/ Data layer
├── queries.ts Client-side Supabase queries (with RLS)
├── queries-server.ts Server-side queries (SSR)
├── mutations.ts Server Actions for all writes
├── timeline-actions.ts Timeline-specific Server Actions
├── types.ts TypeScript interfaces (PaiNode, PaiEdge, RSP*)
├── constants.ts Node colors, type labels, nav links
├── supabase.ts Browser Supabase client
├── supabase-server.ts SSR Supabase client (cookie-based)
└── supabase-middleware.ts Middleware session refresh
supabase/
migrations/ 10 SQL migrations
config.toml Local dev configuration
Astrapai owns the public schema:
| Table | Purpose |
|---|---|
pai_nodes |
Knowledge graph nodes (8 types) with markdown content |
pai_edges |
Directed relationships between nodes with type and weight |
pai_activity |
User activity feed |
pai_timelines |
Timeline definitions with node references and display config |
All tables include user_id with RLS policies enforcing auth.uid() = user_id.
| Function | Description |
|---|---|
get_project_network(root_id, max_depth) |
Recursive CTE with cycle detection and auth.uid() filtering. Default depth 2. SECURITY INVOKER. |
find_timeline_conflicts() |
Detects overlapping timeline entries |
- Server Components fetch via
queries-server.tsusing cookie-based Supabase client - Client Components fetch via
queries.tsusing browser Supabase client with RLS - All mutations go through Server Actions (
mutations.ts,timeline-actions.ts) -- never direct client-side writes - Dashboard fetches everything server-side and passes props to Client Components for interactivity
Astrapai is the visual "Shell" of a larger documentary research ecosystem. It works in tandem with the Research-to-Story Platform (RSP), the logic engine for documentary filmmakers.
| Astrapai | RSP | |
|---|---|---|
| Role | Visual explorer | Logic engine |
| Schema | public (4 tables) |
story_platform (27 tables) |
| Interface | Next.js web app | Claude Code skills |
| Standalone? | Yes (storyboard shows empty state) | Yes (loses graph/timeline views) |
Both repos share a single Supabase project. RSP populates the story_platform schema with narrative data; Astrapai's /storyboard page reads it. All other Astrapai features work without RSP.
To set up both repos together, follow the Master Ecosystem Setup Guide.
npm test # run Vitest test suite
npm run lint # ESLint via next lint
npx tsc --noEmit # type checking
npm run build # full production buildAll four checks run automatically on every PR via GitHub Actions.
- All routes auth-gated via middleware (except
/loginand/auth/*) - Row Level Security on every table -- queries cannot leak across users
- Server Actions for all mutations -- no client-side Supabase writes
anonrole revoked onstory_platformschema- Assertion Lockdown blocks script updates when disputed fact claims exist
See SECURITY.md for vulnerability reporting guidelines.
See CONTRIBUTING.md for guidelines. Issues and feature requests are welcome -- please open an issue before submitting a pull request.
MIT -- Copyright (c) 2026 O-Side Media
Built by O-Side Media