Alexandria

A web app for learning topics through curated "Cards" - structured collections of high-quality sources.

Prerequisites

• Node.js 18+
• Docker (for PostgreSQL)

Quick Start

# 1. Install dependencies
npm install

# 2. Set up environment
cp .env.example .env
# Edit .env: change JWT_SECRET to a secure random string (min 32 chars)

# 3. Start PostgreSQL
docker compose up -d

# 4. Run database migrations and seed data
npm run db:generate -w @alexandria/backend
npm run db:migrate -w @alexandria/backend
npm run db:seed -w @alexandria/backend

# 5. Start the app (two terminals)
npm run dev:backend   # Terminal 1: Backend on http://localhost:3000
npm run dev           # Terminal 2: Frontend on http://localhost:5173

Frontend only (no backend needed)

The frontend works standalone using localStorage:

npm run dev

OAuth Setup (optional)

To enable login, configure OAuth credentials in .env:

• Google: Google Cloud Console > APIs & Services > Credentials
• GitHub: GitHub Developer Settings > OAuth Apps

Available Scripts

Command	Description
npm run dev	Start frontend (port 5173)
npm run dev:backend	Start backend (port 3000)
npm run build	Build all packages

Database Commands

npm run db:generate -w @alexandria/backend  # Generate migrations from schema
npm run db:migrate -w @alexandria/backend   # Apply migrations
npm run db:seed -w @alexandria/backend      # Seed with sample data
npm run db:studio -w @alexandria/backend    # Open Drizzle Studio (DB GUI)

Project Structure

alexandria/
├── packages/
│   ├── frontend/          # React + Vite + Tailwind
│   ├── backend/           # Fastify + Drizzle ORM
│   └── shared/            # Shared TypeScript types
├── spec/                  # Specifications & docs
├── docker-compose.yml     # PostgreSQL for development
└── .env.example           # Environment template

Tech Stack

• Frontend: React, TypeScript, Vite, Tailwind CSS, React Router
• Backend: Fastify, TypeScript, Drizzle ORM, PostgreSQL
• Auth: OAuth 2.0 (Google, GitHub)