Moheeb Zara
8ad1ca44b7
Production deploy completed (DigitalOcean Droplet, self-hosted Supabase, Caddy + Let's Encrypt, GitHub Actions auto-deploy on push to main, daily pg_dumpall backups). This commit lands the work that came out of the deep audit pass and the open-source release prep. Audit fixes: - Webhook signing secret is now displayed in the settings UI with show/hide and copy-to-clipboard; the broken external docs.hackerspace.sh link is replaced with a link to the new local docs. - Settings updateSpaceSettings parameter type now includes mission_statement so the field persists. - members page enforces member_directory_visibility for non-admin viewers (admin_only, board_visible, members_visible). - Mobile responsiveness pass: Projects Kanban grid, Members + Payments tables (column hiding on small screens), Proposal tally + voting buttons (2-col on mobile). Open-source release scaffolding: - LICENSE (MIT). - CONTRIBUTING.md with dev setup, conventions, PR flow. - SECURITY.md with disclosure policy. - CHANGELOG.md. - docs/WEBHOOKS.md with Node and Python signature verification examples. - README.md rewritten for an open-source audience. Removed v0/Vercel references: - @vercel/analytics dependency removed. - app/layout.tsx no longer imports Analytics, drops generator: 'v0.app'. - Canonical deployment docs (docs/DEPLOYMENT.md, docs/README.md, docs/ARCHITECTURE.md, DATABASE.md, CLAUDE.md, README.md) now describe the self-hosted Droplet target only. - e2e console-error check no longer filters [v0] noise. Landing page: - GitHub icon link to the public repo in the nav and footer.
224 lines
5.8 KiB
Markdown
224 lines
5.8 KiB
Markdown
# Hackerspace.sh Documentation
|
|
|
|
> **Version**: 1.0.0
|
|
> **Last Updated**: 2026-03-10
|
|
> **Status**: Pre-Production
|
|
|
|
---
|
|
|
|
## Documentation Index
|
|
|
|
| Document | Description |
|
|
|----------|-------------|
|
|
| [ARCHITECTURE.md](./ARCHITECTURE.md) | System overview, tech stack, project structure, auth flows |
|
|
| [DATABASE_SCHEMA.md](./DATABASE_SCHEMA.md) | Complete schema reference, enums, relationships, RLS |
|
|
| [API_REFERENCE.md](./API_REFERENCE.md) | All server actions, parameters, return types |
|
|
| [COMPONENT_REFERENCE.md](./COMPONENT_REFERENCE.md) | React components, props, usage patterns |
|
|
| [PRODUCTION_AUDIT.md](./PRODUCTION_AUDIT.md) | Security audit, issues, action plan |
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
### Development Setup
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```env
|
|
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 | Self-hosted DigitalOcean Droplet (Docker, Caddy) |
|
|
|
|
---
|
|
|
|
## 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
|
|
|
|
1. Create page in `app/(app)/feature/page.tsx` (Server Component)
|
|
2. Create client component in `app/(app)/feature/feature-client.tsx`
|
|
3. Add server action in `lib/actions.ts`
|
|
4. Add navigation link in `components/app-sidebar.tsx`
|
|
5. Update types in `lib/types.ts` if needed
|
|
|
|
### Add Database Table
|
|
|
|
1. Create migration script in `scripts/0XX_description.sql`
|
|
2. Define table with RLS policies
|
|
3. Run migration via Supabase SQL Editor
|
|
4. Add TypeScript interface to `lib/types.ts`
|
|
5. Update `docs/DATABASE_SCHEMA.md`
|
|
|
|
### Add Server Action
|
|
|
|
1. Add function to `lib/actions.ts`
|
|
2. Include auth check: `supabase.auth.getUser()`
|
|
3. Include membership check
|
|
4. Include role check if needed
|
|
5. Add Zod validation (recommended)
|
|
6. Call `revalidatePath()` for cache
|
|
7. 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
|
|
|
|
### DigitalOcean Droplet (production)
|
|
|
|
See [DEPLOYMENT.md](./DEPLOYMENT.md) for the at-a-glance flow and [DEPLOY_DO_SELFHOSTED.md](./DEPLOY_DO_SELFHOSTED.md) for the end-to-end provisioning procedure. Every push to `main` triggers GitHub Actions, which runs the deploy script on the Droplet over SSH.
|
|
|
|
### Database Migrations
|
|
|
|
Migrations must be run manually via Supabase SQL Editor:
|
|
1. Open Supabase Dashboard → SQL Editor
|
|
2. Run migration scripts in order
|
|
3. 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:
|
|
```typescript
|
|
console.log('[app] User:', user?.id, 'Space:', member?.space_id)
|
|
```
|
|
|
|
View logs with `journalctl -u hackerspace-app -f` on the Droplet, or in the dev server terminal locally.
|
|
|
|
---
|
|
|
|
## Support
|
|
|
|
- GitHub Issues: Report bugs and feature requests
|
|
- Documentation: This folder
|
|
- Code: Well-commented in key areas
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
[Add license information]
|