3-action.md

This document acts as the project's tactical execution log and roadmap, tracking the step-by-step implementation status across all development phases. It records completed milestones, such as the migration to Mikro-ORM and the establishment of the monorepo structure, while outlining remaining tasks for future development iterations. # AudivaMax Implementation Plan This document outlines the step-by-step plan to build AudivaMax. ## Phase 1: Project Initialization & Infrastructure Setup - [x] **Repository Setup** - [x] Initialize Git repository. - [x] Configure `.gitignore` for Node.js, Next.js, and environment files. - [x] Set up linting (ESLint) and formatting (Prettier). - [x] **Database Setup** - [x] Install and configure PostgreSQL. - [x] Design database schema (Users, Books, Authors, Narrators, Genres, Orders). - [x] Implement **UUID v7** as the primary key for all records to ensure time-ordered uniqueness. - [x] Create initial migration scripts (Handled via Sequelize Sync for MVP). - [x] **Backend Scaffold** - [x] Initialize Node.js/Express project in `src/server`. - [x] Set up environment variable configuration (dotenv). - [x] Configure database connection (Sequelize). - [x] **Frontend Scaffold** - [x] Initialize Next.js project in `src/client`. - [x] Configure Tailwind CSS. - [x] Set up React Context/Hooks for state management. ## Phase 2: Backend Core Services - [x] **User Authentication API** - [x] Implement Registration endpoint (POST /api/auth/register). - [x] Implement Login endpoint (POST /api/auth/login) with JWT. - [x] Implement "Get Current User" endpoint (GET /api/auth/me). - [x] Middleware for JWT verification and user role validation. - [x] **Catalog Management API** - [x] Create CRUD endpoints for Books (Admin only). - [x] Implement dedicated endpoints for Authors and Genres (GET /api/books/authors, GET /api/books/genres). - [x] Implement "Get Book Details" and search/filtering. - [x] **File Storage & Streaming** - [x] Implement disk-based storage for audio files (stored in `src/server/uploads/audio`) to prevent database bloat. - [x] Implement binary storage in PostgreSQL for cover images. - [x] Create endpoint to stream audio files directly from disk. - [x] Create endpoint to serve cover art. - [x] **Library & Orders API** - [x] Implement "Add to Library" and purchase tracking. - [x] Implement Progress Tracking for audio playback. ## Phase 3: Frontend Implementation - [x] **Modern UI/UX Redesign** - [x] Implement "Premium" design language with Glassmorphism. - [x] Integrated `Framer Motion` for smooth animations and transitions. - [x] Enhanced Tailwind v4 theme with sophisticated indigo/violet palette. - [x] **Authentication UI** - [x] Login Page with AuthContext integration. - [x] Sign Up Page. - [x] **Storefront & Catalog** - [x] **Homepage:** Redesigned Hero with animated audio waves and featured books. - [x] **Browse Page:** Grid/List views with live filtering by category and search. - [x] **Site Completeness** - [x] Created all missing marketing and utility pages: Membership, Cart, About, Contact, Press, Careers, Help, Redeem, New Releases, Bestsellers, Originals. - [x] Implemented Legal pages: Privacy Policy, Terms of Service, Cookie Policy. - [x] **Audio Player** - [x] Persistent Glassmorphism Player Bar. - [x] Interactive progress seeking, volume control, and playback speed. ## Phase 4: Admin & Management - [x] **Admin Dashboard** - [x] Removed `/dashboard` route from the public web app (use `/admin` for management). - [ ] (Removed) Optimized UI with compact layout and reduced font sizes for better information density. - [ ] (Removed) Implemented real-time stats (Total Users, Books, Revenue). - [ ] (Removed) System controls for site maintenance and registrations. - [x] **Book Management (CRUD)** - [x] Built complex modal for adding/editing books. - [x] Refined modal UI for a more compact and user-friendly experience. - [x] Integrated `multer` for multipart form data (Cover Images & Audio Files). - [x] Real-time inventory updates and deletion handling. ## Phase 5: Production & Deployment - [x] **Server Configuration** - [x] Configured Nginx as a reverse proxy with SSL (Certbot). - [x] Fixed PostgreSQL authentication issues using Unix socket peer auth. - [x] Increased server upload limits to **900MB** (Nginx, Express, and Multer) to support large audiobook files. - [x] **Process Management** - [x] Set up PM2 for zero-downtime process management. - [x] Optimized `ecosystem.config.js` for Client and Server. - [x] Created automated deployment script `/doc/build.sh` for one-command rebuilds and restarts. - [x] **Live Environment** - [x] Successfully deployed to [https://audivamax.com/](https://audivamax.com/). - [x] Verified full-stack connectivity and database synchronization. ## Phase 6: Post-Launch & Scaling - [x] **Internal Credit System** - [x] Added `credits` field to User model. - [x] Implemented `/api/auth/add-credit` endpoint for credit management. - [x] Integrated "Add Credit" UI (removed from `/dashboard` route). - [ ] **Email Service** - [ ] Integrate SMTP for registration confirmations and password resets. - [ ] **Payment Integration** - [ ] Replace internal library logic with real Stripe/PayPal payments. - [ ] **Content Expansion** - [ ] Bulk upload of Audiobook catalog. - [ ] Narration profiling and narrator detail pages. - [x] **Mobile App** - [x] Evaluate Capacitor or React Native for mobile wrapper. - [x] Implement iOS-compatible audiobook download system. - [x] Add M4B format support and proper binary headers. # Actions Taken - Mobile App Support & iOS Downloads ## API Enhancements (`apps/api`) - **Authorization Payload Update**: - Updated `POST /v1/playback/authorize` to return the snake_case format expected by the iOS client: `download_url`, `hls_playlist_url`, `expires_at`, `file_size`, `checksum`, and `qualities`. - Dynamically calculates the actual `file_size` from the filesystem. - **Dedicated Download Endpoint**: - Created `GET /v1/library/:bookId/download` with support for: - **Token Auth via Query**: Allows `URLSessionDownloadTask` to authenticate via `?token=...`. - **iOS Compatibility**: Forces `.m4b` extension in `Content-Disposition` for M4A/M4B sources. - **Resumability**: Full support for HTTP `Range` headers for large file downloads. - **URL Versioning Fix**: - Standardized `baseUrl` to include the `/v1` prefix across all media-serving controllers. - Injected auth tokens into the `audioUrl` returned by the library sync for seamless mobile integration. ## Middleware & Security - **Auth Fallback**: Updated `protect` middleware to prioritize `Authorization` headers but robustly fall back to `query.token` for background processes. - **Audit Logging**: Added granular logging for the download lifecycle to identify ownership or filesystem issues in real-time. # Actions Taken - Backend Migration (Sequelize to Mikro-ORM) ## Documentation - **Updated `doc/design.md`**: Reformatted Section 7 to match the document's style and conventions. ## Database (`packages/db`) - **Generated Initial Migration**: Created the initial Mikro-ORM migration to set up the database schema for `User`, `Book`, `Author`, `Narrator`, `Genre`, and `UserLibrary`. - **Verified Configuration**: Confirmed `mikro-orm.config.ts` matches the Sequelize model definitions. ## API (`apps/api`) - **Auto-Migrations**: Updated `src/index.ts` to automatically apply pending database migrations on server startup. - **Dependency Cleanup**: Removed `sequelize` and `pg-hstore` from `package.json`. - **Code Migration (JS -> TS & Sequelize -> Mikro-ORM)**: - **Controllers**: - Created `src/controllers/bookController.ts` - Created `src/controllers/authController.ts` - Created `src/controllers/libraryController.ts` - **Routes**: - Created `src/routes/bookRoutes.ts` - Created `src/routes/authRoutes.ts` - Created `src/routes/libraryRoutes.ts` - **Middleware**: - Created `src/middleware/authMiddleware.ts` - **Entry Point**: - Updated `src/index.ts` to import the new TypeScript routes and config. - **Validation**: - Created `src/middleware/validate.ts` containing `validateBody` and `validateQuery` helper functions. - Integrated validation into `authRoutes.ts` (Login/Register), `bookRoutes.ts` (List queries), and `libraryRoutes.ts` (Progress updates). ## Contracts & Client Layer - **Created `packages/contracts`**: - Defined Zod schemas for `Auth`, `Catalog`, and `Library`. - Exported inferred TypeScript types for use across the monorepo. - **Created `packages/client`**: - Implemented a type-safe `ApiClient` using Axios and types from `@audivamax/contracts`. - Included specific endpoints for: - **Auth**: login, register, getMe, addCredits. - **Catalog**: list, get, getGenres, getAuthors, getNarrators, delete. - **Library**: list, add, updateProgress. - Automatic JWT token injection via Axios interceptors. ## Database & Migrations - **Migration Generation**: - `Migration20251226011509.ts`: Initial schema creation for core entities. - `Migration20251226020000.ts`: Added subscription fields to `User` and created the `Order` table. - **Auto-Migration**: Configured `apps/api/src/index.ts` to automatically run `orm.getMigrator().up()` on server start. ## Purchases, Entitlements & Playback - **Database Enhancement**: - Created `Order` entity in `packages/db` to track book purchases and Stripe session IDs. - Added `subscriptionTier`, `subscriptionStatus`, and `nextBillingDate` to `User` entity. - Registered `Order` in Mikro-ORM configuration. - **API Implementation**: - Created `checkoutController.ts` for handling Stripe session creation (mocked) and webhooks. - Created `playbackController.ts` for authorizing playback and generating signed URLs. - Created `subscriptionController.ts` for handling upgrades and cancellations. - Created `checkoutRoutes.ts`, `playbackRoutes.ts`, and `subscriptionRoutes.ts` with validation. - Registered new routes in `apps/api/src/index.ts`. - **Client Support**: - Updated `ApiClient` in `packages/client` with `purchase`, `playback`, and `subscription` methods. ## Frontend (`apps/web`) - **API Integration**: Refactored `lib/api.ts` to use the shared `@audivamax/client`. - **Legacy Compatibility**: Maintained existing `authApi`, `bookApi`, and `libraryApi` interfaces but backed them with the new `apiClient` to minimize breaking changes. - **Dynamic Content**: Updated the Homepage and Browse page to fetch and display real data from the API using the new client. - **Auth Sync**: Updated `AuthContext.tsx` to keep the `apiClient` authentication state in sync with the application's login/logout lifecycle. - **Checkout Flow**: Updated `BookDetailPage` to use the new `purchase.createCheckoutSession` flow. - **Fulfillment**: Implemented mock fulfillment in `LibraryPage` to handle `session_id` redirection and order completion. - **Protected Playback**: Updated `PlayerContext.tsx` to use `playback.authorize` for fetching signed stream URLs. - **Membership Management**: Created `membership/page.tsx` to allow users to upgrade to premium or cancel their subscription. - **Image Handling**: Integrated `bookApi.getBookCoverUrl` for consistent cover art delivery across components. ## Build & Deployment - **Configuration**: Updated `ecosystem.config.js` to support the new monorepo structure (`audivamax-api` and `audivamax-web`). - **Port Update**: Configured `audivamax-web` to use port **3016** for the production frontend. - **Automation**: Rewrote `doc/build.sh` to use `pnpm` and `turbo build` for efficient, ordered building of all packages and applications. ## Admin Panel Implementation **Goal:** Build a "Django Admin"-like interface for managing content, users, and orders, as specified in `doc/design.md` Section 6. ### 1. Workspace Setup - [x] **Initialize `apps/admin`**: Create a new Next.js 16 application. - [x] **Workspace Config**: Update `pnpm-workspace.yaml` and `turbo.json`. - [x] **Port Allocation**: Assign port **3017**. - [x] **Ecosystem**: Add `audivamax-admin` to `ecosystem.config.js`. ### 2. Backend Admin API (`apps/api`) - [x] **RBAC Middleware**: Using existing `admin` middleware. - [x] **Dynamic Query Engine**: Created `adminController.ts` to handle generic CRUD operations via Mikro-ORM. - [x] **Model Registry**: Created `apps/api/src/config/admin.ts` to map resources to Entities. - [x] **Generic Endpoints**: - `GET /admin/resources`: List resources. - `GET /admin/resources/:resource`: List records. - `GET /admin/resources/:resource/:id`: Get record. - `POST /admin/resources/:resource`: Create. - `PATCH /admin/resources/:resource/:id`: Update. - `DELETE /admin/resources/:resource/:id`: Delete. ### 3. Frontend Core (`apps/admin`) - [x] **Layout**: Created `Sidebar` component and main Layout. - [x] **Authentication**: Implemented `AuthContext` and `login/page.tsx` using `packages/client`. - [x] **Data Client**: Created `adminApi` in `lib/api.ts`. - [x] **Dashboard**: Implemented `page.tsx` to list available resources. - [x] **List View**: Implemented `resources/[resource]/page.tsx` with dynamic table and delete actions. ### 4. Next Steps - [x] **Form View**: Implement `resources/[resource]/[id]/page.tsx` for creating/editing records with dynamic inputs. - [x] **Relationship Handling**: Add support for selecting foreign keys (e.g., Author dropdown when editing a Book). - [x] **Validation**: Integrate Zod schemas for client-side form validation. - [x] **Search & Pagination**: Implemented search input and pagination controls in the list view. ## Operational Fixes & User Management - **Admin User Creation**: Created the initial superuser account (`superuser@audivamax.com`) using a custom CLI script in `apps/api/src/scripts/create-admin.ts`. - **Port Conflict Resolution**: Resolved an issue where a rogue Node.js process was occupying port 5000, preventing the legitimate `audivamax-api` from handling requests correctly. - **Admin Panel Configuration**: - Fixed a CORS and connectivity issue in the Admin Panel by configuring `NEXT_PUBLIC_API_URL` in `apps/admin/.env`. - Rebuilt and restarted the `audivamax-admin` service to ensure it correctly points to the production API (`https://audivamax.com/api`).