Bandcheck

Music discovery platform with community-contributed content warnings.

📚 Documentation

The comprehensive architecture documentation is located in the architecture/ directory.

Quick Links

• Architecture Overview - Complete system documentation
• Getting Started Guide - Goals and requirements
• Deployment Guide - Infrastructure and CI/CD
• Architectural Decisions - Key design decisions

What's Inside

• Technology Stack: React, TypeScript, Bun, SQLite, Kubernetes
• Architecture Pattern: Hexagonal architecture (ports & adapters)
• Infrastructure: Kubernetes, Docker, Cloudflare (DNS + CDN)
• CI/CD: GitHub Actions (build) + ArgoCD (deployment)
• Security: Auth0 authentication, Cloudflare Turnstile bot protection
• Compliance: GDPR, German TMG, EU E-Commerce Directive

🚀 Quick Start

Frontend Development

cd frontend
npm install
npm run dev

Opens on http://localhost:5173

Backend Development

cd backend
bun install
bun dev

Runs on http://localhost:3000

📖 Additional Documentation

• Frontend README: frontend/README.md
• Backend README: backend/README.md
• Architecture Docs: architecture/README.md

🏗️ Project Structure

bandcheck/
├── architecture/          # Complete architecture documentation (AsciiDoc)
├── backend/              # Backend API (Bun + TypeScript)
│   ├── src/
│   │   ├── core/        # Business logic (hexagonal architecture)
│   │   ├── adapters/    # HTTP, database adapters
│   │   └── db/          # Database schema
│   └── k8s/             # Kubernetes manifests
├── frontend/            # Frontend SPA (React + TypeScript)
│   ├── src/
│   │   ├── pages/       # Page components
│   │   ├── components/  # Reusable components
│   │   └── services/    # API client
│   └── k8s/             # Kubernetes manifests
└── infrastructure/      # Terraform configuration

🤝 Contributing

This is an open-source, non-profit project. Contributions are welcome!

1. Read the architecture documentation
2. Check the hexagonal architecture guide
3. Follow TypeScript best practices
4. Write tests for new features
5. Submit a pull request

📝 License

See LICENSE file for details.

🔗 Related Links

• Auth0: Authentication provider
• Cloudflare Turnstile: Bot protection
• Kubernetes (K3s): Container orchestration
• Drizzle ORM: Type-safe database access