WIP. A little custom music server
add ISSUES.md to track unresolved shit
+39
+39
backend/ISSUES.md
+39
backend/ISSUES.md
···
1
+
# Architectural Issues & Tasks
2
+
3
+
## High Priority (Stability & Performance)
4
+
- [ ] **Fix Critical Memory Usage in `FlacService`**
5
+
- **Location**: `src/flac/service.ts`
6
+
- **Issue**: `readMetadata` uses `fs.readFile` to load entire audio files (often 20-100MB) into memory just to read headers.
7
+
- **Task**: Implement partial reads (open file descriptor -> read buffer) to parse headers and Vorbis comments without loading the binary audio data.
8
+
9
+
- [ ] **Implement Pagination for API Endpoints**
10
+
- **Location**: `src/api.ts`
11
+
- **Issue**: `getAlbumList` and `getAllSongs` fetch the entire database table in a single query.
12
+
- **Task**: Add limit/offset or cursor-based pagination parameters to these endpoints and updated the database queries accordingly.
13
+
14
+
- [ ] **Optimize Library Synchronization**
15
+
- **Location**: `src/file-parser.ts` & `src/sync-library.ts`
16
+
- **Issue**: `readDirectory` and the sync stream load all file paths into memory before processing. `alreadyIndexed` loads the entire file table.
17
+
- **Task**: Refactor to use a streaming directory iterator and batched database lookups to handle large libraries (50k+ songs) without OOM.
18
+
19
+
## Medium Priority (Reliability & Maintainability)
20
+
- [ ] **Standardize API Error Handling**
21
+
- **Location**: `src/api.ts`
22
+
- **Issue**: Inconsistent error handling. Some endpoints map errors explicitly, others rely on `runtime.runPromise` which may cause unhandled promise rejections or generic 500s for domain errors.
23
+
- **Task**: Create a standardized wrapper or middleware that executes Effects and maps specific `TaggedError` types to HTTP status codes (404, 400, etc.).
24
+
25
+
- [ ] **Decouple API from Database Logic**
26
+
- **Location**: `src/api.ts`
27
+
- **Issue**: API handlers contain `db.query` and `db.select` calls directly ("Active Record" pattern in controllers).
28
+
- **Task**: Extract database queries into a dedicated Repository layer or specific Service methods to enable unit testing without a database connection.
29
+
30
+
## Low Priority (Code Quality)
31
+
- [ ] **Refactor Effect <-> Elysia Adapter**
32
+
- **Location**: `src/api.ts`
33
+
- **Issue**: Manual calls to `runtime.runPromise` in every handler create boilerplate.
34
+
- **Task**: specific utility helper to bind Effect workflows directly to Elysia handlers.
35
+
36
+
- [ ] **Externalize Configuration**
37
+
- **Location**: `src/index.ts`
38
+
- **Issue**: Server port `3003` is hardcoded.
39
+
- **Task**: Use Effect's `Config` module to make the port configurable via environment variables.