Moheeb Zara
ea8d7a5f91
Adds proposals + proposal_votes + policies + incidents + incident_updates
tables with full RLS, async voting flow, dismissal-appeal pathway,
versioned policies with provenance, and an anonymous-incident token mode.
Adds per-space configurable areas, financial visibility settings, member
self-profile + COI disclosure, and a mission statement that renders in
the app footer.
Reorganises lib/actions.ts into per-domain files (tasks, projects,
members, payments, contacts, knowledge-base, secrets, area-leads,
settings, imports, proposals, incidents, policies, areas) plus a barrel.
Adds lib/permissions.ts and lib/auth-helpers.ts so action bodies stop
duplicating the user-to-member-to-role check. Wires every action that has
a Zod schema; introduces a flexibleDateTime preprocessor so HTML date
pickers no longer hit "Invalid datetime".
Hardens RLS: drops NOT NULL on space_members.user_id for offline members,
adds a privilege-escalation trigger that blocks self-edits to role / tier
/ status / approved / has_card_access / space_id, closes four
cross-tenant holes in the governance kernel, and adds a partial unique
index so two admins cannot concurrently activate two drafts of the same
policy slug.
Ships every deployment artifact: Dockerfile, docker-compose,
.do/app.yaml, .env.example, /api/health, plus a managed-Supabase guide
(docs/DEPLOYMENT.md), an end-to-end self-hosted Droplet guide
(docs/DEPLOY_DO_SELFHOSTED.md), and a Supabase-CLI local-dev quickstart
(docs/LOCAL_DEV.md). Replaces middleware.ts with proxy.ts for Next.js 16.
Adds scripts/schema.sql as the canonical idempotent full deploy plus
fourteen numbered incremental migrations.
Adds scripts/seed.sql so a fresh local DB renders something instead of
empty pages: a demo space, five members across all roles, a v1 code of
conduct, three proposals in different states with seven votes already
cast, an open incident, a project, three tasks, a KB entry, and matching
activity-log rows.
Replaces v0-generated test scaffolding with 266 real tests across
__tests__/{actions,auth-helpers,components,governance,permissions,
security,utils,validations}.test.ts. Adds react-markdown + remark-gfm
for proposal / incident / policy body rendering. Deletes four dead v0
fix-* scripts, the unused components/app-shell.tsx, and the duplicate
app/auth/login/page.tsx.
Routes (31 total): /api/health, /api/paypal/sync, /auth/callback, /,
/login, /signup, /signup/confirm, /dashboard, /tasks, /projects,
/members, /payments, /financials, /contacts, /ops, /ops/[id], /ops/new,
/proposals, /proposals/[id], /proposals/new, /incidents, /incidents/[id],
/incidents/new, /policies, /policies/[slug], /policies/new, /profile,
/recruitment, /settings, /comms, /import.
Full pass-by-pass history is in docs/HANDOFF.md; the roadmap is in
docs/GOVERNANCE_FEATURES.md.
Hackerspace.sh Documentation
Version: 1.0.0
Last Updated: 2026-03-10
Status: Pre-Production
Documentation Index
| Document | Description |
|---|---|
| ARCHITECTURE.md | System overview, tech stack, project structure, auth flows |
| DATABASE_SCHEMA.md | Complete schema reference, enums, relationships, RLS |
| API_REFERENCE.md | All server actions, parameters, return types |
| COMPONENT_REFERENCE.md | React components, props, usage patterns |
| PRODUCTION_AUDIT.md | Security audit, issues, action plan |
Quick Start
Development Setup
# Clone and install
git clone <repo>
cd hackerspace-sh
pnpm install
# Set environment variables
cp .env.example .env.local
# Edit .env.local with your Supabase credentials
# Run database migrations
# Execute scripts/001_create_schema.sql through scripts/011_*.sql in order
# Start development server
pnpm dev
Environment Variables
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
SUPABASE_JWT_SECRET=your-jwt-secret
Application Overview
What is Hackerspace.sh?
A comprehensive member management platform for hackerspaces, makerspaces, and community workshops. Features include:
- Member Management - Registration, approval, roles, payment tracking
- Task System - One-time tasks and recurring chores
- Project Tracking - Kanban-style project management
- Payment Reconciliation - Multi-platform payment integration
- Communications - Real-time chat via Supabase Realtime
- Knowledge Base - Documentation and secrets management
- Contact Directory - Vendors, suppliers, partners
Tech Stack
| Layer | Technology |
|---|---|
| Frontend | Next.js 16, React 19, TypeScript, Tailwind CSS |
| UI | shadcn/ui component library |
| Backend | Next.js Server Actions |
| Database | Supabase PostgreSQL |
| Auth | Supabase Auth |
| Real-time | Supabase Realtime |
| Hosting | Vercel |
Key Concepts
Spaces
A "space" represents a single hackerspace organization. Each space has:
- Unique slug and invite code
- Its own members, tasks, projects, etc.
- Independent settings and integrations
Membership
Users belong to spaces via the space_members table:
- A user can belong to multiple spaces
- Each membership has a role (admin, board, treasurer, member, associate)
- Status tracks account state (current, late, inactive, unverified)
Roles & Permissions
| Role | Capabilities |
|---|---|
| Admin | Full access to everything |
| Board | Members, payments, projects, board-level KB |
| Treasurer | Payments and financial data |
| Member | Tasks, projects, comms, public KB |
| Associate | Read-only, can claim chores |
Row Level Security
All database access is protected by RLS policies:
- Users can only see data from their space
- Role-based write permissions
- Enforced at the database level
Common Tasks
Add a New Feature
- Create page in
app/(app)/feature/page.tsx(Server Component) - Create client component in
app/(app)/feature/feature-client.tsx - Add server action in
lib/actions.ts - Add navigation link in
components/app-sidebar.tsx - Update types in
lib/types.tsif needed
Add Database Table
- Create migration script in
scripts/0XX_description.sql - Define table with RLS policies
- Run migration via Supabase SQL Editor
- Add TypeScript interface to
lib/types.ts - Update
docs/DATABASE_SCHEMA.md
Add Server Action
- Add function to
lib/actions.ts - Include auth check:
supabase.auth.getUser() - Include membership check
- Include role check if needed
- Add Zod validation (recommended)
- Call
revalidatePath()for cache - Update
docs/API_REFERENCE.md
Code Style
TypeScript
- Use strict types, avoid
any - Define interfaces in
lib/types.ts - Use Zod for runtime validation
React
- Server Components for data fetching
- Client Components for interactivity
- Use
'use client'directive explicitly
Styling
- Tailwind CSS utility classes
- shadcn/ui design tokens (
bg-background,text-foreground) - Monospace font for labels:
font-mono text-[10px]
File Naming
- Pages:
page.tsx - Client components:
feature-client.tsx - Server actions:
lib/actions.ts - Types:
lib/types.ts
Deployment
Vercel
- Connect GitHub repository
- Set environment variables in Vercel dashboard
- Deploy automatically on push to main
Database Migrations
Migrations must be run manually via Supabase SQL Editor:
- Open Supabase Dashboard → SQL Editor
- Run migration scripts in order
- Verify with
SELECT * FROM pg_tables WHERE schemaname = 'public'
Troubleshooting
Common Issues
| Issue | Solution |
|---|---|
| "Not authenticated" | Check session, redirect to login |
| "No active membership" | User needs to create/join space |
| RLS policy error | Check user has correct role |
| Infinite redirect | Check middleware, layout redirects |
| Stale data | Call revalidatePath() or router.refresh() |
Debug Mode
Add console logs in server actions:
console.log('[v0] User:', user?.id, 'Space:', member?.space_id)
View logs in Vercel Function logs or terminal.
Support
- GitHub Issues: Report bugs and feature requests
- Documentation: This folder
- Code: Well-commented in key areas
License
[Add license information]