net/docs/DEVELOPER_GUIDE.md

DEVELOPER GUIDE: Spark Platform Setup & Workflow

BLUF: Clone, install, run docker-compose up -d then npm run dev. Access admin at localhost:4321/admin. Git push triggers auto-deploy.

---

1. Prerequisites

Requirement	Version	Check Command
Node.js	20+	node --version
npm	10+	npm --version
Docker	24+	docker --version
Docker Compose	2.x	docker compose version
Git	2.x	git --version

---

2. Clone & Install

# Clone repository
git clone https://github.com/jumpstartscaling/net.git spark
cd spark

# Install frontend dependencies
cd frontend
npm install
cd ..

---

3. Environment Configuration

# Copy example environment file
cp .env.example .env

Required Variables

Variable	Purpose	Example
PUBLIC_DIRECTUS_URL	API endpoint	https://spark.jumpstartscaling.com
DIRECTUS_ADMIN_TOKEN	SSR authentication	(from Directus admin)
POSTGRES_PASSWORD	Database auth	(secure password)

Development Overrides

For local development, create frontend/.env.local:

PUBLIC_DIRECTUS_URL=http://localhost:8055
DIRECTUS_ADMIN_TOKEN=your-local-token

---

4. Start Services

Option A: Full Stack (Docker)

# Start all containers
docker-compose up -d

# View logs
docker-compose logs -f

# Stop all
docker-compose down

Services available:

• PostgreSQL: localhost:5432
• Redis: localhost:6379
• Directus: localhost:8055
• Frontend (if containerized): localhost:4321

Option B: Frontend Development (Recommended)

# Connect to staging/production Directus
cd frontend
npm run dev

Access: http://localhost:4321

---

5. Local Development Workflow

5.1 File Structure

frontend/src/
├── pages/
│   ├── admin/          # Admin pages (.astro)
│   ├── api/            # API endpoints (.ts)
│   └── [...slug].astro # Dynamic router
├── components/
│   ├── admin/          # Admin React components
│   ├── blocks/         # Page builder blocks
│   └── ui/             # Shadcn-style primitives
├── lib/
│   ├── directus/       # SDK client & fetchers
│   └── schemas.ts      # TypeScript types
└── hooks/              # React hooks

5.2 Creating New Admin Page

1. Create page file:

touch frontend/src/pages/admin/my-feature/index.astro

2. Add content:

---
import AdminLayout from '@/layouts/AdminLayout.astro';
import MyComponent from '@/components/admin/MyComponent';
---

<AdminLayout title="My Feature">
    <MyComponent client:load />
</AdminLayout>

3. Create component:

touch frontend/src/components/admin/MyComponent.tsx

5.3 Creating New API Endpoint

1. Create endpoint file:

touch frontend/src/pages/api/my-feature/action.ts

2. Add handler:

import type { APIRoute } from 'astro';
import { getDirectusClient } from '@/lib/directus/client';

export const POST: APIRoute = async ({ request }) => {
    const body = await request.json();
    const client = getDirectusClient();
    
    // Your logic here
    
    return new Response(JSON.stringify({ success: true }), {
        status: 200,
        headers: { 'Content-Type': 'application/json' }
    });
};

5.4 Creating New Block Type

1. Create block component:

touch frontend/src/components/blocks/MyBlock.tsx

2. Add component:

interface MyBlockProps {
    content: string;
    settings?: Record<string, any>;
}

export function MyBlock({ content, settings }: MyBlockProps) {
    return (
        <section className="py-12">
            <div className="container mx-auto">
                {content}
            </div>
        </section>
    );
}

3. Register in BlockRenderer.tsx:

case 'my_block':
    return <MyBlock key={block.id} {...block.settings} />;

---

6. Testing

6.1 Build Verification

cd frontend
npm run build

Must complete without errors before push.

6.2 Type Checking

npm run astro check

6.3 Manual Testing

1. Start dev server: npm run dev
2. Open http://localhost:4321/admin
3. Test your changes
4. Check browser console for errors
5. Check network tab for API failures

---

7. Debugging

7.1 React Query Devtools

Enabled in development. Click floating panel (bottom-right) to inspect:

• Active queries
• Cache state
• Refetch status

7.2 Vite Inspector

Access: http://localhost:4321/__inspect/

Shows:

• Module graph
• Plugin timing
• Bundle analysis

7.3 Container Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f directus
docker-compose logs -f frontend

7.4 Database Access

docker exec -it spark-postgresql-1 psql -U postgres -d directus

Useful queries:

-- List tables
\dt

-- Check collection
SELECT * FROM sites LIMIT 5;

-- Recent work log
SELECT * FROM work_log ORDER BY timestamp DESC LIMIT 10;

---

8. Code Style

8.1 TypeScript

• Strict mode enabled
• Explicit return types for functions
• Use types from schemas.ts

8.2 React Components

• Functional components only
• Props interface above component
• Use React Query for data fetching

8.3 File Naming

Type	Convention	Example
Page	lowercase	index.astro
Component	PascalCase	SiteEditor.tsx
Hook	camelCase	useSites.ts
API	kebab-case	generate-article.ts

8.4 Commit Messages

feat: Add new SEO analysis feature
fix: Resolve pagination bug in article list
docs: Update API reference
refactor: Extract shared utility functions

---

9. Git Workflow

9.1 Branch Strategy

Branch	Purpose
main	Production (auto-deploys)
feat/*	New features
fix/*	Bug fixes

9.2 Typical Flow

# Create feature branch
git checkout -b feat/my-feature

# Make changes
# ... edit files ...

# Verify build
cd frontend && npm run build

# Commit
git add .
git commit -m "feat: Description"

# Push (triggers Coolify on main)
git push origin feat/my-feature

# Create PR for review
# Merge to main after approval

---

10. Deployment

10.1 Auto-Deploy (Standard)

git push origin main

Coolify detects push and deploys within ~2-3 minutes.

10.2 Verify Deployment

1. Check Coolify dashboard for build status
2. Test production URL after successful build
3. Check container logs if issues

10.3 Environment Variables

Set in Coolify Secrets:

• GOD_MODE_TOKEN
• DIRECTUS_ADMIN_TOKEN
• FORCE_FRESH_INSTALL (only for schema reset)

10.4 Rollback

In Coolify:

1. Go to service
2. Click "Deployments"
3. Select previous deployment
4. Click "Redeploy"

---

11. Common Issues

Build Fails

# Check for TypeScript errors
npm run astro check

# Verify schemas.ts matches actual collections
# Check for missing dependencies
npm install

API 403 Errors

• Verify DIRECTUS_ADMIN_TOKEN is set
• Check Directus permissions for token
• Verify CORS includes your domain

SSR Errors

• Check client.ts SSR URL detection
• Verify Docker network connectivity
• Check container names match expected

Database Connection

# Verify container is running
docker-compose ps

# Check PostgreSQL logs
docker-compose logs postgresql

---

12. Useful Commands

# Frontend
npm run dev          # Start dev server
npm run build        # Production build
npm run preview      # Preview production build

# Docker
docker-compose up -d          # Start all
docker-compose down           # Stop all
docker-compose logs -f        # Stream logs
docker-compose restart directus  # Restart service

# Git
git status           # Check changes
git diff             # View changes
git log -n 5         # Recent commits