feat: add comprehensive documentation and configuration files for Box System architecture, workflows, and Codex integration

.codex/config.json

@@ -0,0 +1,34 @@
+{
+  "version": 1,
+  "project": "box-nestjs-monorepo",
+  "description": "Box System: NestJS monorepo with mgnt/app/stats APIs, MySQL, MongoDB, Redis, and heavy ads traffic.",
+  "read_context": [
+    "docs/ARCHITECTURE.md",
+    "docs/SYSTEM_OVERVIEW.md",
+    "docs/API_FLOW_DIAGRAMS.md",
+    "docs/HIGH_LEVEL_MERMAID_DIAGRAMS.md",
+    "docs/DEVELOPMENT_CHECKLIST.md",
+    "docs/DEPLOYMENT_GUIDE.md",
+    "docs/CODEX_ONBOARDING.md"
+  ],
+  "preferences": {
+    "languages": [
+      "typescript"
+    ],
+    "frameworks": [
+      "nestjs"
+    ],
+    "style": {
+      "testsPreferred": true,
+      "avoidBreakingChanges": true
+    }
+  },
+  "rules": [
+    "Always generate TypeScript for backend code unless explicitly told otherwise.",
+    "Follow the architecture and flows described in docs/ARCHITECTURE.md and docs/API_FLOW_DIAGRAMS.md.",
+    "Prefer NestJS patterns: modules, controllers, services, guards, interceptors.",
+    "Respect existing DTOs, Prisma schemas, and naming conventions.",
+    "When refactoring, preserve backward compatibility whenever reasonably possible.",
+    "Before generating code, summarize the intended change and potential impact."
+  ]
+}

docs/API_FLOW_DIAGRAMS.md

@@ -0,0 +1,36 @@
+# API Flow Diagrams (Maker–Checker Removed)
+
+## 1. Mgnt Update Flow (Immediate Publish)
+```mermaid
+sequenceDiagram
+  participant M as Mgnt User
+  participant MgntAPI
+  participant DB as MySQL/Mongo
+  participant Redis
+
+  M->>MgntAPI: Update content (ads/videos/channels)
+  MgntAPI->>DB: Save changes with audit trails
+  MgntAPI->>Redis: Update relevant keys
+  MgntAPI-->>M: Success, published immediately
+```
+
+## 2. Ad Placement Flow
+```mermaid
+sequenceDiagram
+  participant U as User
+  participant App as App API
+  participant Redis
+  participant Mongo
+
+  U->>App: GET /ads/placement
+  App->>Redis: GET cached ad pool
+  alt hit
+    Redis-->>App: pool
+    App-->>U: Ad response
+  else miss
+    App->>Mongo: Query ads
+    App->>Redis: Rebuild ad pool
+    App-->>U: Response
+  end
+```
+

docs/ARCHITECTURE.md

@@ -0,0 +1,68 @@
+# Box System Architecture (Audit-Only, Immediate Publish)
+
+## 1. Overview
+The Box System is a high-performance video content and advertisement platform built using a NestJS monorepo. It consists of:
+- Management API (box-mgnt-api)
+- Application API (box-app-api)
+- Stats API (future: box-stats-api)
+- Shared libraries: common, core, db
+- Datastores: MySQL, MongoDB, Redis
+
+This updated architecture **removes Maker–Checker**, uses **audit-only trails**, and adopts **immediate publish** behavior.
+
+## 2. RBAC Roles
+- **SuperAdmin**: Full system access, including managing users and roles.
+- **Manager**: Manage content (ads, videos, channels), system params.
+- **Admin**: Similar to Manager with limited permissions.
+- **Viewer**: Read-only access.
+
+Only SuperAdmin can:
+- Create users
+- Assign roles
+- Change roles
+- Disable accounts
+
+## 3. Audit Trail Model
+Kept fields:
+- createdBy  
+- createdAt  
+- updatedBy  
+- updatedAt  
+- lastUpdated  
+
+These appear in MySQL and MongoDB content models.
+
+## 4. Data Flow
+### Mgnt API
+User updates → validation → save to DB → update Redis cache → immediate publish.
+
+### App API
+Requests go to Redis first:
+- Ads served from prebuilt pools
+- Videos served partly cached
+- Fallback to Mongo where applicable (future extension)
+
+### Stats API (Upcoming)
+Handles:
+- Event ingestion
+- Redis queue/stream
+- Workers writing aggregated stats
+
+## 5. Modules
+### Mgnt Modules
+- Ads  
+- Ads Module  
+- Videos  
+- Categories  
+- Channels  
+- Tags  
+- System Params  
+- Upload / File service  
+
+### App Modules
+- Ads placement  
+- Video listing  
+- Homepage aggregation  
+- System params  
+- Categories  
+

docs/CODEX_CI_CHECKLIST.md

@@ -0,0 +1,102 @@
+# Codex + CI Checklist
+
+Goal: Use Codex as a powerful assistant **without** breaking the Box System or letting unreviewed AI code slip into production.
+
+This checklist is for every feature or refactor where Codex is involved.
+
+---
+
+## 1. Before You Ask Codex
+
+- [ ] **Create a feature branch** from `main` or `develop`: - Example: `feature/auto-registration-device-code`.
+- [ ] **Confirm docs are up to date**: - `docs/ARCHITECTURE.md` - `docs/SYSTEM_OVERVIEW.md` - `docs/DEVELOPMENT_CHECKLIST.md` - `docs/ROADMAP.md`
+- [ ] **Clarify the task in your own words**: - What are you changing? - Which app? (`box-mgnt-api`, `box-app-api`, `box-stats-api`) - What are the constraints? (e.g. “no breaking changes”, “BigInt timestamps”)
+
+---
+
+## 2. When Prompting Codex
+
+- [ ] **Mention the project context**: - “We are in `box-nestjs-monorepo` (NestJS + TypeScript, MySQL, Mongo, Redis).”
+- [ ] **Tell Codex to read the docs** referenced in `.codex/config.json`.
+- [ ] **Use a structured prompt** (from `docs/CODEX_PROMPTS.md`), including: - Architecture reference. - Tech stack. - Constraints: - TypeScript only. - NestJS patterns. - BigInt epoch for timestamps. - Avoid breaking changes.
+- [ ] **Ask for a plan before code**: - “Step 1: Summarize current design.” - “Step 2: Propose changes and list affected files.” - “Step 3: Wait for confirmation before generating TypeScript code.”
+
+---
+
+## 3. Reviewing Codex’s Plan
+
+- [ ] Check the **alignment with architecture**: - Does the plan match `ARCHITECTURE.md` and `API_FLOW_DIAGRAMS.md`?
+- [ ] Check **scope vs roadmap**: - Is the change consistent with the current phase in `ROADMAP.md`?
+- [ ] Check **dependencies & impact**: - Which modules, services, DTOs, and DB schemas are affected?
+- [ ] If anything feels off: - [ ] Ask Codex to revise the plan. - [ ] Or narrow the scope.
+
+Do **not** accept auto-generated code if the plan itself looks wrong.
+
+---
+
+## 4. Generating Code with Codex
+
+- [ ] Ask Codex to: - Generate TypeScript code **in small chunks** (one module/file at a time). - Clearly label which file each snippet belongs to.
+- [ ] Verify: - [ ] Uses TypeScript and NestJS decorators correctly. - [ ] Respects BigInt timestamps for date/time fields. - [ ] Uses existing conventions from `libs/common`, `libs/core`, `libs/db`.
+- [ ] Manually **paste code into files** (or let Codex apply edits, but still review them).
+
+---
+
+## 5. Local Verification (Before Commit)
+
+- [ ] Run **TypeScript compilation**: - `pnpm build` or `pnpm lint` + `pnpm tsc` equivalent.
+- [ ] Run **linters & formatters**: - `pnpm lint` - `pnpm format` (if applicable)
+- [ ] Run **tests**: - `pnpm test` (or app-specific test commands)
+- [ ] If schema changed: - [ ] Run Prisma format & generate: - `pnpm prisma:format` - `pnpm prisma:generate` - [ ] Apply local migrations to dev DB (if needed).
+- [ ] Test **key endpoints** manually with curl/Postman: - Especially: - New/modified endpoints. - Auth-protected routes. - Redis-related flows (ad placement, stats events).
+
+If anything fails, fix it yourself or ask Codex for a focused correction (with error logs included in the prompt).
+
+---
+
+## 6. Preparing the Pull Request
+
+- [ ] Create a **clear PR title**: - Example: `feat(app-api): auto-register users by device_code`.
+- [ ] In the PR description, include: - [ ] Summary of the change. - [ ] Which parts were generated or heavily assisted by Codex. - [ ] Link to **relevant docs** in `docs/` (architecture, roadmap). - [ ] Any potential risks or backward-compatibility notes.
+- [ ] Attach **testing evidence**: - [ ] Commands you ran (lint, test, build). - [ ] Screenshots/logs for manual endpoint tests if useful.
+
+---
+
+## 7. Code Review (Human + Codex-Assisted)
+
+Reviewer checklist:
+
+- [ ] Understand the **functional goal** of the change.
+- [ ] Confirm architecture alignment: - Modules/controllers/services match design.
+- [ ] Check for: - [ ] Hardcoded secrets or credentials. - [ ] Direct DB access bypassing `libs/db` abstractions. - [ ] Inconsistent DTOs or response shapes. - [ ] Missing validation on inputs.
+- [ ] Check **error handling & logging**: - Are important failures logged in a structured way?
+- [ ] Optionally, use Codex again: - Ask it to review a specific file/method for: - Complexity. - Edge cases. - Missing null/undefined handling.
+
+---
+
+## 8. CI Integration
+
+- [ ] Ensure your CI pipeline runs on each PR: - Lint - Tests - Build (optional)
+- [ ] If CI fails: - [ ] Fix locally. - [ ] Re-run tests. - [ ] Push updates.
+- [ ] Do **not** override CI protections** to merge failing PRs**, even if Codex generated the code.
+
+---
+
+## 9. After Merge
+
+- [ ] Monitor logs/metrics in the relevant environment: - Error rates. - Latency. - Queue depth (for stats).
+- [ ] If issues appear: - [ ] Create a hotfix branch. - [ ] Optionally use Codex to assist in debugging, but: - Keep changes small and review carefully.
+
+---
+
+## 10. Golden Rules
+
+1. Codex is a **power tool**, not an excuse to skip thinking.
+2. Docs in `docs/` are **the source of truth**; Codex must follow them.
+3. Never merge Codex-generated changes **without**:
+   - Passing tests.
+   - At least one human review.
+4. When in doubt:
+   - Reduce the scope.
+   - Add more tests.
+   - Ask Codex for a design explanation before touching code.

docs/CODEX_ONBOARDING.md

@@ -0,0 +1,18 @@
+# Codex Onboarding (Audit-Only Version)
+
+Codex should follow:
+- Audit-only changes
+- Immediate publish workflows
+- RBAC roles: SuperAdmin, Manager, Admin, Viewer
+- No Maker–Checker logic
+
+When generating code:
+- Refer to architecture docs
+- Use TypeScript only
+- Maintain backward compatibility
+
+Codex should:
+1. Read docs in /docs  
+2. Analyze impacted modules  
+3. Propose design before code  
+4. Follow audit trail conventions  

docs/CODEX_PROMPTS.md

@@ -0,0 +1,66 @@
+# Codex Prompt Templates for Box Monorepo
+
+## 1. General Feature Implementation (Backend, NestJS, TypeScript)
+
+**Use this when adding a new feature.**
+
+> You are working in the `box-nestjs-monorepo` project (NestJS + TypeScript).
+> Read and respect the project docs in `docs/`:
+>
+> - ARCHITECTURE.md
+> - SYSTEM_OVERVIEW.md
+> - API_FLOW_DIAGRAMS.md
+> - DEVELOPMENT_CHECKLIST.md
+> - DEPLOYMENT_GUIDE.md
+> - CODEX_ONBOARDING.md
+>
+> Task:
+>
+> 1. Summarize the relevant architecture and flows for this task.
+> 2. Propose the NestJS module/controller/service/DTO design in a bullet list.
+> 3. After that, ask me if I am ready for TypeScript code.
+>
+> Requirements:
+>
+> - Use **TypeScript only**.
+> - Follow existing folder structures under `apps/` and `libs/`.
+> - Use Redis/Mongo/MySQL access patterns already present in the codebase, unless you explicitly propose a better one.
+> - Maintain backward compatibility with existing APIs and DTOs where possible.
+> - Keep date/time fields as **BigInt epoch** values in the data layer (as per project rules).
+>
+> Task details:
+> [Describe the feature here, e.g. “Implement auto-registration of users by device_code in box-app-api, including MySQL schema changes and service logic.”]
+
+---
+
+## 2. Refactor / Cleanup Prompt
+
+> You are refactoring existing code in `box-nestjs-monorepo`.
+> First:
+>
+> 1. Inspect the current implementation and summarize what it does.
+> 2. Identify risks of breaking changes.
+> 3. Propose a safer refactor plan (steps).
+> 4. Only then, after I confirm, generate TypeScript changes.
+>
+> Rules:
+>
+> - Do **not** rename public APIs or DTO fields unless necessary and explicitly agreed.
+> - Preserve external behavior.
+> - Improve readability, testability, and consistency with patterns in `libs/common` and `libs/core`.
+
+---
+
+## 3. Docs-Driven Implementation Prompt
+
+> Use `docs/ARCHITECTURE.md`, `docs/SYSTEM_OVERVIEW.md`, and `docs/API_FLOW_DIAGRAMS.md` as the source of truth.
+> I want you to:
+>
+> 1. Read those docs.
+> 2. Explain how the requested feature fits into the architecture.
+> 3. List the affected files/modules (existing and new).
+> 4. Propose a small, incremental implementation plan (1–3 PRs).
+> 5. Only after I confirm, start generating TypeScript code.
+>
+> Feature:
+> [Describe feature here]

docs/DEPLOYMENT_GUIDE.md

@@ -0,0 +1,21 @@
+# Deployment Guide
+
+## 1. Requirements
+- Node 20+  
+- pnpm  
+- Redis  
+- MongoDB  
+- MySQL  
+
+## 2. Build
+```
+pnpm install
+pnpm build
+```
+
+## 3. Run with PM2
+```
+pm2 start dist/apps/box-mgnt-api/main.js
+pm2 start dist/apps/box-app-api/main.js
+```
+

docs/DEVELOPMENT_CHECKLIST.md

@@ -0,0 +1,40 @@
+# Development Checklist (Audit-Only)
+
+## Phase 0 – Foundation
+- Setup monorepo  
+- Setup MySQL, MongoDB, Redis  
+- Configure base NestJS apps  
+- Setup libs/common, libs/db  
+
+## Phase 1 – Auth & RBAC
+- Implement login  
+- JWT  
+- 2FA  
+- RBAC roles: SuperAdmin, Manager, Admin, Viewer  
+- Only SuperAdmin can manage users/roles  
+
+## Phase 2 – Mgnt Modules
+- Ads  
+- Videos  
+- Channels  
+- Categories  
+- Tags  
+- System Params  
+- Upload service  
+- Audit trails only  
+- Immediate publish workflow  
+
+## Phase 3 – App API
+- Ads placement  
+- Homepage data  
+- Video listing  
+- Redis-driven ad pools  
+
+## Phase 4 – Stats Pipeline (Future)
+- Event ingestion  
+- Redis stream/queue  
+
+## Phase 5–8 (Future)
+- Optimization  
+- Monitoring  
+- Advanced features  

docs/HIGH_LEVEL_MERMAID_DIAGRAMS.md

@@ -0,0 +1,27 @@
+```mermaid
+flowchart LR
+  subgraph Mgnt API
+    A1(Content Mgmt)
+    A2(System Params)
+  end
+
+  subgraph App API
+    B1(Ad Placement)
+    B2(Video Listing)
+  end
+
+  subgraph Datastores
+    MSQL[(MySQL)]
+    MONGO[(MongoDB)]
+    REDIS[(Redis)]
+  end
+
+  A1-->MSQL
+  A1-->MONGO
+  A1-->REDIS
+
+  B1-->REDIS
+  B2-->MONGO
+
+  App API-->REDIS
+```

docs/ROADMAP.md

@@ -0,0 +1,19 @@
+# Roadmap (Updated for Audit-Only)
+
+## Phase 0
+Monorepo, environment, database setup.
+
+## Phase 1
+Auth + RBAC (SuperAdmin-only user management).
+
+## Phase 2
+Mgnt modules with audit-only flows.
+
+## Phase 3
+App API core ads/videos.
+
+## Phase 4
+Stats system (future).
+
+## Phase 5–8
+Optimization, scalability, monitoring.

docs/SYSTEM_OVERVIEW.md

@@ -0,0 +1,21 @@
+# System Overview (Audit-Only, Immediate Publish)
+
+The Box System is a multi-API backend platform built for large-scale content delivery and advertisement placement.  
+
+## Key Principles
+- **Immediate publish**: No Maker–Checker, no approval steps.
+- **Audit-only tracking**: Every change is logged but applied instantly.
+- **RBAC enforcement**: SuperAdmin has full control; Managers/Admins handle content.
+- **Redis-first architecture** for ad/video responses.
+- **MongoDB for content**, **MySQL for admin**, **Redis for performance**.
+
+## Components
+1. **box-mgnt-api (Management)**  
+   Admin tool for managing ads, videos, channels, categories, system parameters.
+
+2. **box-app-api (Consumer)**  
+   Public API serving ads, videos, homepage data.
+
+3. **box-stats-api (Future)**  
+   Event ingestion and stats aggregation.
+