https://github.com/hazeliscoding/bloomwatch
A shared anime tracking platform for pairs and small groups.
https://github.com/hazeliscoding/bloomwatch
angular anime-tracker dotnet scalar
Last synced: about 1 month ago
JSON representation
A shared anime tracking platform for pairs and small groups.
- Host: GitHub
- URL: https://github.com/hazeliscoding/bloomwatch
- Owner: hazeliscoding
- Created: 2026-03-13T15:07:16.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-10T21:21:40.000Z (2 months ago)
- Last Synced: 2026-04-10T21:33:09.536Z (2 months ago)
- Topics: angular, anime-tracker, dotnet, scalar
- Language: C#
- Homepage:
- Size: 1.09 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 25
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# ๐ธ BloomWatch
> A shared anime tracking platform for pairs and small groups.
BloomWatch lets friends maintain a joint backlog, track watch progress, leave separate ratings, and discover how compatible their taste really is โ no more spreadsheets or Discord threads!
## โจ Features
- **Watch Spaces** โ Create shared spaces for you and your watch partner(s)
- **AniList Integration** โ Search and add anime directly from AniList, with cached metadata
- **Individual Progress** โ Everyone tracks their own episodes and status independently
- **Ratings & Reviews** โ Personal 0.5โ10 ratings with optional notes
- **Compatibility Analytics** โ See how your ratings align, find your biggest disagreements, and get random backlog picks
- **Kawaii/Y2K Design** โ A playful pastel design system with gel effects, light/dark themes, and custom components
## ๐ Tech Stack
| Layer | Tech |
|-------|------|
| **Backend** | .NET 10 ยท ASP.NET Core Minimal APIs ยท PostgreSQL ยท EF Core 9 ยท JWT auth |
| **Frontend** | Angular 21 ยท SCSS design tokens ยท Vitest |
| **Architecture** | DDD-inspired modular monolith (5 modules, one DB schema each) |
| **Testing** | 700+ automated tests (180 xUnit backend + 527 Vitest frontend) |
| **API Docs** | OpenAPI + [Scalar](https://scalar.com/) interactive explorer at `/scalar/v1` |
## ๐ Quick Start
**Prerequisites:** [.NET 10 SDK](https://dotnet.microsoft.com/download) ยท [Node.js 18+](https://nodejs.org/) ยท PostgreSQL ยท [Docker](https://www.docker.com/) (optional, for local email)
```bash
# 1. Clone and restore
git clone && cd bloomwatch
dotnet restore
# 2. Configure the database (override if your setup differs)
# Default: Host=localhost;Database=bloomwatch;Username=postgres;Password=postgres
export ConnectionStrings__DefaultConnection="Host=localhost;Database=bloomwatch;Username=youruser;Password=yourpass"
# 3. (Optional) Start Mailpit to capture invitation emails locally
docker run -d -p 1025:1025 -p 8025:8025 axllent/mailpit
# โ SMTP on localhost:1025 ยท Web UI at http://localhost:8025
# 4. Apply migrations and start the API
./scripts/apply-migrations.sh
dotnet run --project src/BloomWatch.Api
# โ http://localhost:5192 (API docs at /scalar/v1)
# 5. Start the frontend
cd src/BloomWatch.UI && npm install && npm start
# โ http://localhost:4200
```
## ๐๏ธ Database Scripts
Use the helper scripts in [scripts/](scripts/) for common EF Core database tasks:
```bash
# Apply all module migrations
./scripts/apply-migrations.sh
# Create a migration for one module
./scripts/add-migration.sh
# Drop the database (with confirmation)
./scripts/drop-database.sh
# Drop the database without confirmation (automation/CI)
./scripts/drop-database.sh --force
```
Supported modules for `add-migration.sh`:
- `identity`
- `watchspaces`
- `anilistsync`
- `animetracking`
Example:
```bash
./scripts/add-migration.sh identity AddRefreshTokenTable
```
## ๐งช Running Tests
```bash
dotnet test # All backend tests
cd src/BloomWatch.UI && npm test # Frontend tests
```
Backend integration tests use in-memory SQLite via `WebApplicationFactory` โ no running database needed.
## ๏ฟฝ Interactive API Docs (Scalar)
With the API running (`dotnet run --project src/BloomWatch.Api`), open **[http://localhost:5192/scalar/v1](http://localhost:5192/scalar/v1)** in your browser to access the Scalar API explorer.
Scalar provides:
- **Browse all 30 endpoints** grouped by module (Identity, WatchSpaces, AniList, AnimeTracking, Analytics, Home)
- **Try requests live** โ fill in parameters, set headers, and execute calls against your local API
- **Authenticate** โ click the ๐ lock icon, paste a JWT obtained from `POST /auth/login`, and all subsequent requests include the `Authorization: Bearer` header automatically
- **View request/response schemas** โ expand any endpoint to see the full JSON shape, required fields, and status codes
> **Tip:** Register a user via `POST /auth/register`, then log in via `POST /auth/login` to get a token. Paste it into Scalar's auth dialog and you can explore every protected endpoint interactively.
The raw OpenAPI JSON spec is also available at [`/openapi/v1.json`](http://localhost:5192/openapi/v1.json) for importing into other tools (Postman, Insomnia, etc.).
## ๐ Project Structure
```
src/
โโโ BloomWatch.Api/ # HTTP host, endpoint registration, middleware
โโโ BloomWatch.SharedKernel/ # Cross-cutting abstractions
โโโ BloomWatch.UI/ # Angular frontend (features, shared UI, design system)
โโโ Modules/
โโโ Identity/ # Registration, login, JWT, user profiles
โโโ WatchSpaces/ # Watch space CRUD, invitations, membership
โโโ AniListSync/ # AniList GraphQL proxy with persistent caching
โโโ AnimeTracking/ # Anime lifecycle, progress, ratings per watch space
โโโ Analytics/ # Compatibility scores, rating gaps, shared stats
tests/ # Unit + integration tests per module (10 xUnit projects)
docs/ # Architecture, UI/UX doctrine, user stories, wireframes
openspec/ # Spec-driven change tracking (see below)
```
Each module follows a consistent DDD layering: **Domain โ Application โ Infrastructure โ Contracts**.
## ๐งฉ Modules
| Module | Schema | Responsibility |
|--------|--------|---------------|
| **Identity** | `identity` | User registration, login, JWT authentication, and profile management |
| **WatchSpaces** | `watch_spaces` | Shared space lifecycle, invitations, membership, and ownership transfer |
| **AniListSync** | `anilist_sync` | AniList GraphQL proxy with persistent `media_cache` table (24-hour freshness) and in-memory search cache (5-minute TTL) |
| **AnimeTracking** | `anime_tracking` | Per-space anime lifecycle, shared group status, individual participant progress/ratings |
| **Analytics** | *(read-only)* | Compatibility scores, rating gap analysis, shared stats, dashboard summaries, and random backlog picks |
Modules communicate through **read-only cross-module `DbContext`s** โ never by calling another module's services or repositories directly. This preserves bounded context isolation while sharing a single database.
## ๐จ Design System
The frontend ships a custom `bloom-*` component library with a kawaii/Y2K aesthetic (Quicksand + Nunito typefaces, pastel palette, gel effects). Components include buttons, cards, inputs, badges, avatars, modals, a compatibility ring, and a backlog picker.
Design tokens, animations, and utilities live in `src/BloomWatch.UI/src/app/shared/styles/`. See [`docs/ui-ux-doctrine.md`](docs/ui-ux-doctrine.md) for the full design system reference.
## ๐ Architecture
This is a **modular monolith** โ five domain modules sharing a single deployment but separated by schema, bounded context, and clean cross-module contracts.
See [`docs/architecture.md`](docs/architecture.md) for the full design doc covering module boundaries, database strategy, and planned feature phases.
## ๐ OpenSpec Workflow
BloomWatch uses a spec-driven change management workflow. Every feature is planned as a proposal with a design doc, feature specs, and a task checklist before implementation begins.
```
propose โ apply โ archive
```
Completed changes are archived in `openspec/changes/archive/`. Feature specs live in `openspec/specs/`.
## ๐ License
MIT