+
From cb7bf75d388b82545ad145822b8aa9df55b5dd73 Mon Sep 17 00:00:00 2001
From: Eric Jinks <3147296+Jinksi@users.noreply.github.com>
Date: Sat, 16 Aug 2025 22:57:33 +1000
Subject: [PATCH 2/3] Add database documentation and npm script
- Add comprehensive Astro DB documentation to CLAUDE.md
- Document database schema, actions, and development workflow
- Add npm run db:push script for schema deployment
- Update development commands with database-related scripts
---
CLAUDE.md | 45 +++++++++++++++++++++++++++++++++++++++++++--
package.json | 3 ++-
2 files changed, 45 insertions(+), 3 deletions(-)
diff --git a/CLAUDE.md b/CLAUDE.md
index 2525a1f..42e7a1f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -5,12 +5,14 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
## Development Commands
- **Dev server**: `npm run dev` (starts Astro dev server on localhost:4321)
-- **Build**: `npm run build` (fetches GitHub stars, then generates static site in `dist/`)
+- **Dev server (with DB)**: `npm run dev:remote` (starts dev server with remote database connectivity)
+- **Build**: `npm run build` (fetches GitHub stars, then generates static site in `dist/` with remote DB)
- **Preview**: `npm run preview` (serves built site for testing)
- **Tests**: `npm run test:e2e` (runs Playwright E2E tests)
- **Single test**: `npx playwright test tests/specific-test.spec.ts`
- **Format**: `npx prettier --write .`
- **Fetch GitHub stars**: `npm run fetch-stars` (updates cached star data from GitHub REST API)
+- **Database push**: `npm run db:push` (pushes local schema changes to remote database)
- I'll be running the dev server in the background
- To view GitHub dependabot autodetected vulnerabilities, use 'gh api repos/Jinksi/ericjinks.com/dependabot/alerts'
@@ -26,6 +28,7 @@ This is a personal blog/portfolio website built with **Astro** as the primary fr
### Tech Stack
- **Framework**: Astro 5.x (static site generation with hybrid SSR)
+- **Database**: Astro DB (LibSQL/SQLite with local development and remote production)
- **UI Libraries**: React 18, Svelte 5, TypeScript
- **Content**: Astro Content Collections with Zod schema validation
- **Styling**: SCSS with CSS custom properties, dark/light theme support
@@ -45,6 +48,10 @@ This is a personal blog/portfolio website built with **Astro** as the primary fr
- `react/` subdirectory for React components requiring client-side interactivity
- `ml/` subdirectory for TensorFlow.js machine learning demos
+- **`src/actions/`**: Astro Actions (server-side functions)
+ - `index.ts` - Type-safe server actions for database operations
+ - Exports `getCounter` and `incrementCounter` actions for admin functionality
+
- **`src/sketches/`**: Canvas-based generative art using canvas-sketch library
- Each sketch has corresponding `.ts`/`.tsx` file and MDX content file
- Uses Two.js, canvas-sketch, and custom Vector utilities
@@ -62,9 +69,13 @@ This is a personal blog/portfolio website built with **Astro** as the primary fr
- Fetched via REST API using `scripts/fetch-github-stars.js`
- **Authentication**:
- `/login/` - Admin login page with form-based authentication
- - `/admin/` - Protected admin dashboard (requires authentication)
+ - `/admin/` - Protected admin dashboard with interactive counter functionality
- `/api/logout/` - Logout endpoint supporting both GET and POST requests
+- **`db/`**: Database configuration and seeding
+ - `config.ts` - Astro DB schema definition with Counter table
+ - `seed.ts` - Database seeding script for initial data
+
### Content Management
Content is managed through Astro Content Collections with strict TypeScript schemas:
@@ -124,6 +135,36 @@ Single-user admin authentication with the following components:
- Creates cycling blocks for automated attacks while allowing legitimate use
- Prevents brute force attacks and conserves Netlify function invocations
+### Database System
+
+Astro DB integration for persistent data storage:
+
+- **Database Engine**: LibSQL (SQLite-compatible) with local development and remote production
+- **Schema Definition** (`db/config.ts`):
+ - `Counter` table with `id` (text, primary key), `name` (text, unique), `count` (number, default 0)
+ - Uses Astro's `defineDb` and `defineTable` for type-safe schema definitions
+
+- **Data Seeding** (`db/seed.ts`):
+ - Initialises database with `adminCounter` starting at 0
+ - Uses `crypto.randomUUID()` for unique ID generation
+
+- **Server Actions** (`src/actions/index.ts`):
+ - Type-safe server-side functions using Astro Actions
+ - `getCounter`: Retrieves counter by name with error handling
+ - `incrementCounter`: Atomically increments counter value and returns new count
+ - Uses Drizzle ORM queries with `eq()` for safe SQL operations
+
+- **Development Setup**:
+ - Local SQLite database for development (`npm run dev`)
+ - Remote database connectivity for production builds (`npm run dev:remote`, `npm run build`)
+ - Schema changes pushed to remote with `npm run db:push`
+ - Automatic table creation and seeding on first run
+
+- **Client Integration**:
+ - Admin dashboard uses `Astro.callAction()` for server-side data fetching
+ - Client-side JavaScript calls actions for interactive updates
+ - Seamless hydration between server and client state
+
### Testing Strategy
Playwright E2E tests configured to:
diff --git a/package.json b/package.json
index 46f37d8..ed7d381 100644
--- a/package.json
+++ b/package.json
@@ -12,7 +12,8 @@
"preview": "astro preview",
"astro": "astro",
"test:e2e": "playwright test",
- "fetch-stars": "node scripts/fetch-github-stars.js"
+ "fetch-stars": "node scripts/fetch-github-stars.js",
+ "db:push": "astro db push --remote"
},
"dependencies": {
"@astrojs/check": "^0.9.4",
From 8735fb199d6cf4c8fd78c5114e751a7a3a6fc733 Mon Sep 17 00:00:00 2001
From: Eric Jinks <3147296+Jinksi@users.noreply.github.com>
Date: Sat, 16 Aug 2025 23:01:32 +1000
Subject: [PATCH 3/3] Document Turso environment variables and setup
- Add ASTRO_DB_REMOTE_URL and ASTRO_DB_APP_TOKEN to environment variables
- Add Turso CLI setup commands to README for database creation
- Document Remote Database (Turso) section in CLAUDE.md
- Provide clear instructions for getting database URL and auth token
---
CLAUDE.md | 8 ++++++++
README.md | 17 ++++++++++++++++-
2 files changed, 24 insertions(+), 1 deletion(-)
diff --git a/CLAUDE.md b/CLAUDE.md
index 42e7a1f..004a8a7 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -20,6 +20,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
- The GH_TOKEN is in the `.env` file
- Authentication credentials (ADMIN_USERNAME, ADMIN_PASSWORD, ADMIN_SECRET) are in `.env`
+- Database credentials (ASTRO_DB_REMOTE_URL, ASTRO_DB_APP_TOKEN) are in `.env` for Turso integration
- Uses Astro 5.x `astro:env` system for type-safe environment variable access
## Architecture Overview
@@ -160,6 +161,13 @@ Astro DB integration for persistent data storage:
- Schema changes pushed to remote with `npm run db:push`
- Automatic table creation and seeding on first run
+- **Remote Database (Turso)**:
+ - **Required Environment Variables**:
+ - `ASTRO_DB_REMOTE_URL`: Connection URL to LibSQL database (e.g., `libsql://your-db.turso.io`)
+ - `ASTRO_DB_APP_TOKEN`: Authentication token for remote database access
+ - Setup via [Turso](https://turso.tech/) for production LibSQL hosting
+ - Compatible with Astro DB's LibSQL adapter for seamless local/remote development
+
- **Client Integration**:
- Admin dashboard uses `Astro.callAction()` for server-side data fetching
- Client-side JavaScript calls actions for interactive updates
diff --git a/README.md b/README.md
index 3767daa..4c1c6ae 100644
--- a/README.md
+++ b/README.md
@@ -18,9 +18,24 @@ The site includes a secure admin area:
### Environment Variables Required
```bash
+# Authentication
ADMIN_USERNAME=your-admin-username
ADMIN_PASSWORD=your-super-secret-password
ADMIN_SECRET=your-32-char-secret-key
+
+# Database (Turso)
+ASTRO_DB_REMOTE_URL=libsql://your-database.turso.io
+ASTRO_DB_APP_TOKEN=your-turso-auth-token
```
-Generate secure secret: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`
+**Setup Commands:**
+
+```bash
+# Generate secure authentication secret
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+
+# Turso database setup (requires Turso CLI)
+turso db create your-database-name # Create database
+turso db show your-database-name # Get database URL
+turso db tokens create your-database-name # Generate auth token
+```