A full-stack e-commerce platform for selling physical music media — Vinyl, CD, and Cassette. Built with Clean Architecture principles, featuring a rich music catalog, Stripe payments, and an interactive 3D storefront.
Live: catmusicshop.duckdns.org
| Document | Description |
|---|---|
| Business Overview | Feature requirements and business rules |
| ERD Analysis | Full entity-relationship design with rationale |
| API Endpoint Design | REST endpoint specifications |
| Layer | Technology |
|---|---|
| Runtime | .NET 10, C# 12 |
| Architecture | Clean Architecture (Domain → Application → Infrastructure → API) |
| API | RESTful Controllers, API Versioning (/api/v1/) |
| Database | PostgreSQL (pgvector) |
| ORM | Entity Framework Core 10 |
| Auth | JWT + Refresh Tokens, Google OAuth |
| Payments | Stripe (Checkout Sessions + Webhooks) |
| Storage | AWS S3 + CloudFront CDN |
| MailKit (SMTP) | |
| Background Jobs | Hangfire |
| Messaging | Outbox Pattern (reliable event delivery) |
| Logging | Serilog (structured, file sink) |
| Validation | FluentValidation |
| CQRS | MediatR |
| Category | Technology |
|---|---|
| Framework | React 19, TypeScript 5, Vite 8 |
| Styling | TailwindCSS 4 + shadcn/ui |
| State | TanStack Query (server) + Zustand (client) |
| Forms | React Hook Form + Zod |
| 3D | Three.js + React Three Fiber + Drei |
| Routing | React Router v7 |
| HTTP | Axios |
| Component | Technology |
|---|---|
| Containerization | Docker + Docker Compose |
| Reverse Proxy | Nginx + Let's Encrypt SSL |
| Hosting | AWS EC2 |
MusicShop/
├── src/
│ ├── MusicShop.Domain/ # Entities, Enums, Interfaces (zero dependencies)
│ ├── MusicShop.Application/ # Use Cases (CQRS), DTOs, Validators, Events
│ ├── MusicShop.Infrastructure/ # EF Core, S3, Stripe, Email, Outbox Messaging
│ ├── MusicShop.API/ # Controllers, Middleware, DI wiring
│ └── musicshop-web/ # React SPA
├── tests/
├── docs/
├── docker-compose.yml
└── docker-compose.prod.yml
- Browse and filter products by genre, format, artist, country, price, and decade
- Full-text catalog search across albums, tracks, artists, and genres
- Interactive 3D hero scene (Three.js)
- Shopping cart with persistent state
- Stripe checkout with order confirmation emails
- Order tracking and history
- Google OAuth login
- Full CRUD for artists, genres, labels, releases, release versions, and products
- Format-specific attribute management (vinyl color/weight, CD edition, cassette tape color)
- Curated collection editor with custom sort order
- Order management: confirm → ship → deliver → complete
- Order cancellation with reason tracking
- Image uploads to S3
- Outbox Pattern — Domain events are persisted in a transactional outbox and processed by Hangfire, ensuring reliable email delivery even if the mail server is temporarily down
- Snapshot-based Orders — Prices, addresses, and recipient info are captured at checkout time, immune to future data changes
- Format Polymorphism — Vinyl, CD, and Cassette each have dedicated attribute tables linked 1:1 to products, avoiding nullable-column bloat
- Catalog ↔ Sales Separation — Music metadata (artist, release, tracklist) is cleanly separated from sales data (price, stock, availability)
- Clone the repository:
git clone https://github.com/your-username/CatMusicShop.git
cd CatMusicShop/MusicShop- Create a
.envfile from the template and fill in your credentials:
# Database
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_password
POSTGRES_DB=catmusicshop
DB_CONNECTION_STRING=Host=postgres;Port=5432;Database=catmusicshop;Username=postgres;Password=your_password
# App
ASPNETCORE_ENVIRONMENT=Development
# JWT
JWT_SECRET=your_jwt_secret_at_least_32_chars
JWT_ISSUER=CatMusicShop
JWT_AUDIENCE=CatMusicShop
# Google OAuth
GOOGLE_CLIENT_ID=your_google_client_id
# AWS S3
AWS__BucketName=your_bucket
AWS__Region=ap-southeast-1
AWS__CdnBaseUrl=https://your-cdn.cloudfront.net
AWS__AccessKey=your_access_key
AWS__SecretKey=your_secret_key
# Stripe
STRIPE_SECRET_KEY=sk_test_...
STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
# Email (SMTP)
EMAIL_USER=your_email
EMAIL_PASS=your_app_password
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_FROM=CatMusicShop
# Admin Seed
AdminSettings__Email=admin@catmusicshop.com
AdminSettings__Password=YourAdminPassword
AdminSettings__FullName=Admin- Start all services:
docker compose up --build- Access the app:
| Service | URL |
|---|---|
| Frontend | http://localhost:3000 |
| API | http://localhost:5000/api/v1 |
| Swagger | http://localhost:5000/swagger |
Backend:
cd MusicShop/src/MusicShop.API
dotnet runFrontend:
cd MusicShop/src/musicshop-web
npm install
npm run devThis project is for educational and portfolio purposes.