Soedirman Digital Repository — Implementation Plan
| Item | Value |
|---|---|
| Source of truth | docs/PRD.md v1.0 |
| Companion docs | PROJECT_ARCHITECTURE.md, DATABASE_DESIGN.md |
| Scope | MVP, P0 features only (PRD §16). P1/P2 are excluded until P0 is stable. |
| Status | Planning complete. Phase 1 not started. |
| Last updated | 2026-11-04 |
1. Current State Assessment
Section titled “1. Current State Assessment”The workspace was inspected on 2026-11-04 at e:\Mini MBA\Staff IT\Soedirman-Digital-Repository.
| Check | Finding |
|---|---|
| Files present | docs/PRD.md, package.json |
package.json |
0 bytes (empty). It is not valid JSON, so npm install will fail. It contains no dependencies, scripts or configuration. |
Application code (app/, components/, lib/) |
None |
| Next.js / TypeScript / Tailwind / ESLint config | None |
| Prisma schema / migrations / seed | None |
.env.example, .gitignore, README.md |
None |
node_modules / lockfile |
None |
| Git repository | Not initialized |
| Toolchain on the machine | Node v22.14.0, npm 10.9.2, Git, Docker available. pnpm and psql not installed. |
[!IMPORTANT] The brief says the environment and basic application structure were already initialized, but the workspace contains no application scaffold. The only artifact is an empty
package.json. Nothing usable exists yet, so nothing is at risk of being overwritten. Phase 1 must therefore include scaffolding.If the scaffold exists somewhere else (another folder, branch or machine), point to it before Phase 1 starts and this plan will be re-baselined against it.
[!WARNING] The project path contains a space (
Mini MBA). Some native tooling and shell scripts mishandle spaces. All npm scripts must quote paths, and this should be verified early (risk R-10).
2. Gap Analysis (PRD vs. Implementation)
Section titled “2. Gap Analysis (PRD vs. Implementation)”| PRD area | Requirement | Status |
|---|---|---|
| §8.1 Stack | Next.js App Router, TS, Tailwind, shadcn/ui, Lucide | ❌ Not started |
| §7 Database | PostgreSQL + Prisma schema, migrations, seed | ❌ Not started |
| §3 Design system | Steam-inspired tokens, typography, motion | ❌ Not started |
| FR-001 | Homepage (header, featured carousel, latest, categories, all, footer) | ❌ Not started |
| FR-002 | Catalog with search, category filter, 4 sorts, pagination (12) | ❌ Not started |
| FR-003 | Detail page (gallery, lightbox, sidebar, overview, CTAs, metadata, related) | ❌ Not started |
| FR-004 | Category pages | ❌ Not started |
| FR-005 | Header search → /repositories?q= |
❌ Not started |
| FR-006 | Admin login (Auth.js, Argon2id, rate limit) | ❌ Not started |
| FR-007 | Dashboard with 4 stats, recent list, quick action | ❌ Not started |
| FR-008 | Repository management table and actions | ❌ Not started |
| FR-009 / FR-010 | Create/edit form (6 sections), uploads, draft/publish rules | ❌ Not started |
| FR-011 | Category management | ❌ Not started |
| §10 Security | AuthZ in every action, sanitization, upload validation, headers | ❌ Not started |
| §11 SEO | Metadata, OG, canonical, sitemap, robots, 404 | ❌ Not started |
| §12 Performance | Lighthouse ≥ 90, CWV targets | ❌ Not started |
| §19 Tests | Unit, integration, E2E | ❌ Not started |
| §21.19 README | Setup, migration, seed, dev, deploy | ❌ Not started |
Conclusion: this is a greenfield build. The PRD’s stack recommendation (§8.1) has no conflicting existing choices, so it is adopted as-is.
3. Recommended Architecture (summary)
Section titled “3. Recommended Architecture (summary)”Full details are in PROJECT_ARCHITECTURE.md.
- Single Next.js 16 App Router application (modular monolith). Public pages are server-rendered and tag-cached. Admin pages are dynamic and protected.
- PostgreSQL + Prisma 7 (driver adapter
@prisma/adapter-pg,prisma.config.ts). - Auth.js v5 Credentials with JWT cookie, Argon2id, DB-backed rate limiting, and a
session_versioncheck so logout really revokes access. - Server Actions for admin mutations. One Route Handler (
/api/uploads) for multipart images. - S3-compatible storage adapter (MinIO locally, Cloudflare R2 or AWS S3 in production). Images are validated by magic bytes and re-encoded to WebP with
sharp. - Zod schemas shared by client and server, with separate
draftandpublishschemas. - Tailwind v4
@themetokens from PRD §3.2, shadcn/ui primitives, Embla carousel, Tiptap editor (admin bundle only), Sonner toasts, dnd-kit reordering. - Vitest (unit + integration on a real Postgres) and Playwright (E2E + axe).
3.1 PRD-aligned additions (need sign-off)
Section titled “3.1 PRD-aligned additions (need sign-off)”These are not new features. Each one exists so that an explicit PRD requirement can be met.
| Addition | Satisfies |
|---|---|
media_uploads table |
§9 ownership check before deletion, FR-010 “don’t lose data if upload fails”, Flow B step 12 |
auth_rate_limits table |
FR-006 rate limiting, §10.5 brute-force protection (works on multi-instance/serverless hosting) |
admins.session_version |
§10.1 “Logout invalidates session” (JWT sessions can’t otherwise be revoked) |
repositories.search_text (+ pg_trgm) |
FR-002 case-insensitive search over title, short description, developer and tags |
repositories.cover_storage_key, banner_storage_key |
§7.5 (explicitly requested) |
npm run media:cleanup, npm run repositories:purge scripts |
§13 Flow D step 7 “documented retention policy” |
4. Roadmap Overview
Section titled “4. Roadmap Overview”flowchart LR
P1["Phase 1: Foundation"] --> P2["Phase 2: Design System and Public UI"]
P2 --> P3["Phase 3: Authentication and Admin Shell"]
P3 --> P4["Phase 4: Repository CRUD and Media"]
P4 --> P5["Phase 5: QA, SEO and Production Readiness"]
| Phase | Goal | Key deliverable | Indicative effort |
|---|---|---|---|
| 1 | Runnable, typed, DB-connected skeleton | App boots, migrations and seed run, CI-style checks pass | 1–2 days |
| 2 | Complete public website on seeded demo data | All public routes functional and responsive | 3–5 days |
| 3 | Secure admin access and admin navigation | Login/logout, protected dashboard, category management | 2–3 days |
| 4 | Admin can publish real content end-to-end | Create/edit/delete/publish/feature with uploads | 4–6 days |
| 5 | Verified, hardened, deployable | Tests green, SEO, performance, deployment guide | 2–4 days |
Effort assumes one developer with AI assistance. These are planning estimates, not commitments.
Global exit gate for every phase: npm run lint, npm run typecheck, npm run test and npm run build all pass, and the phase checklist is verified manually (PRD §21.16–17). A feature is not reported as done until it has been verified.
5. Phase 1 — Foundation
Section titled “5. Phase 1 — Foundation”Goal: a working Next.js application connected to PostgreSQL with migrations and seeds (PRD §18 Phase 1).
5.1 Tasks
Section titled “5.1 Tasks”- Repository hygiene
-
git init. Add.gitignore(node_modules,.next,.env*except.env.example,generated/, coverage, Playwright reports). - Remove the empty
package.json(it holds no configuration), then scaffold in place withcreate-next-app(TypeScript, App Router, Tailwind, ESLint, nosrc/, import alias@/*). If the scaffolder refuses the non-empty folder, scaffold into a temp folder and move the files in, keepingdocs/untouched. - Pin Node ≥ 22 (
engines,.nvmrc). Choose npm as the package manager (already installed). - TypeScript
strict: true,noUncheckedIndexedAccess: true. - Prettier +
prettier-plugin-tailwindcss. Scripts:dev,build,start,lint,typecheck,format,test,db:migrate,db:seed,db:studio,db:reset.
-
- Local infrastructure
-
docker-compose.yml:postgres:17(databasessdrandsdr_test) andminioplus a bucket-init container (public-read onsdr-media).
-
- Environment
-
.env.examplelisting every variable from PROJECT_ARCHITECTURE §9, with comments. -
lib/env.ts: Zod-validated server and public env, failing fast with a readable error.
-
- Database
- Install
prisma,@prisma/client,@prisma/adapter-pg,pg,dotenv,tsx. -
prisma.config.tsandprisma/schema.prismaper DATABASE_DESIGN §6. - Initial migration plus custom SQL (pg_trgm, functional and partial indexes, DATABASE_DESIGN §6.1).
-
lib/db/client.ts: singleton PrismaClient with the PrismaPg adapter (hot-reload safe),server-only.
- Install
- Seeds
-
lib/auth/password.ts(Argon2id hash/verify), used by the seed. -
prisma/seed.ts: 6 categories (idempotent), admin from env (refuses weak or missing passwords in production), demo repositories only whenSEED_DEMO_DATA=trueand not production, marked [DEMO]. - Demo placeholder images (original, non-copyrighted) in
public/images/demo/, uploaded to MinIO by the seed.
-
- Testing scaffold
- Vitest config with
unitandintegrationprojects. One smoke test per project.
- Vitest config with
- Docs
- Initial
README.md: prerequisites,docker compose up -d, env setup, migrate, seed, dev.
- Initial
5.2 Deliverables & exit criteria
Section titled “5.2 Deliverables & exit criteria”npm run devserves the default page.npm run buildsucceeds.npm run db:migrate && npm run db:seedcreates all tables, indexes, 6 categories, one admin, and the demo data in dev.npx prisma studioshows the seeded data. Passwords are stored as$argon2id$….- Missing or invalid env produces a clear startup error.
6. Phase 2 — Design System & Public UI
Section titled “6. Phase 2 — Design System & Public UI”Goal: a complete, functional public website reading real database records (seeded demo data). Covers PRD §3, FR-001 to FR-005.
6.1 Tasks
Section titled “6.1 Tasks”- Design system
-
globals.css@themetokens (PRD §3.2), Inter vianext/font, typography scale (§3.3), focus-ring and reduced-motion utilities. -
shadcn init(dark theme mapped to the tokens). Add: button, input, select, dialog, sheet, skeleton, badge, dropdown-menu, separator, tooltip.
-
- Public data layer:
lib/repositories/public-queries.tsandlib/categories/service.ts-
listPublishedRepositories,getPublishedRepositoryBySlug,listFeaturedRepositories,listCategories,getRelatedRepositories(PRD §9), with the published filter hard-coded and explicitselect. - Zod parsing of catalog search params (
q≤ 100 chars,categoryslug,sort ∈ latest|oldest|az|za,page ≥ 1). Invalid values fall back to defaults. - Tag-based caching (
repositories,repository:{slug},categories).
-
- Layout:
PublicHeader(logo, Beranda / Jelajahi Repository / Kategori,GlobalSearch, mobileSheetmenu, no login link) andPublicFooter. - Homepage
/(FR-001):FeaturedCarousel(Embla, manual by default, prev/next, keyboard, reduced-motion aware), Latest grid,CategoryCardlist, All Repositories with pagination, and graceful empty states when the DB is empty. - Catalog
/repositories(FR-002, FR-005):CategoryFilter,SortSelect,Pagination,RepositoryGrid/RepositoryCard, all state in the URL query string,EmptyStatewith the text “Tidak ada repository yang ditemukan.”, andloading.tsxwithSkeletonCard. - Detail
/repositories/[slug](FR-003): breadcrumb,RepositoryGallery(main viewer, thumbnails, prev/next, keyboard, swipe on mobile) withLightbox(Dialog),RepositoryInfoSidebar,RepositoryOverview(sanitized HTML, heading “Tentang Produk”, key features list),ProductAccessButtons(render only if URL present,target="_blank" rel="noopener noreferrer"), metadata section,RelatedRepositories(≤ 4, same category, hidden when empty),notFound()for missing or draft slugs. - Category
/categories/[slug](FR-004): header, description, paginated grid, back-to-catalog link, 404 for unknown slug. next/imageconfigured withremotePatternsfromS3_PUBLIC_BASE_URL, stored width/height,priorityonly for the LCP image,sizeson every grid.- Sanitizer
lib/security/sanitize.ts(needed to render the overview) with unit tests against an XSS payload corpus.
6.2 Deliverables & exit criteria
Section titled “6.2 Deliverables & exit criteria”- All public routes work without login on 360 px, 768 px and 1280 px widths with no horizontal scroll.
- Drafts and soft-deleted demo rows (seed one of each) never appear in any listing, detail page or related list.
- Search is case-insensitive across title, short description, developer and tags, and combines with the category filter. State survives reload and back/forward.
- Empty DB: the homepage renders clean empty states with no broken images.
- Keyboard-only navigation works through header, carousel, gallery and lightbox.
7. Phase 3 — Authentication & Admin Shell
Section titled “7. Phase 3 — Authentication & Admin Shell”Goal: an admin can securely log in, navigate the dashboard and manage categories (PRD FR-006, FR-007, FR-011, §10.1–10.2).
7.1 Tasks
Section titled “7.1 Tasks”- Auth.js v5 (pin the exact beta version)
-
lib/auth/auth.config.ts(edge-safe: pages, callbacks) andlib/auth/auth.ts(Credentials provider, Node runtime). -
authorize(): Zod parse, lowercase email, DB lookup, Argon2id verify (dummy verify on unknown email), return{id, name, email, sessionVersion}. - JWT/session callbacks carry
adminIdandsessionVersion.maxAge8 h. Secure cookie flags verified in production mode. -
app/api/auth/[...nextauth]/route.ts.
-
- Authorization guard
lib/auth/require-admin.ts: validates the session andsession_versionagainst the DB, then redirects (pages) or returnsUNAUTHORIZED(actions/handlers). - Rate limiting
lib/auth/rate-limit.tsonauth_rate_limits(per IP + per hashed email). Trusted-proxy-aware IP extraction. proxy.ts: optimistic redirect of unauthenticated/admin/*(except/admin/login) to/admin/login. UX only.- Login page
/admin/login: RHF + Zod, loading state, generic error, redirect to/adminon success, already-authenticated admins redirected to/admin,noindex. - Logout action: increment
session_version,signOut(), redirect to/admin/login. - Admin shell
app/admin/(dashboard)/layout.tsx:requireAdmin(),AdminSidebar(Dashboard, Repository, Categories, Logout),AdminHeader, SonnerToaster,robots: noindex. - Dashboard
/admin(FR-007): 4StatsCards (total, published, draft, featured, excluding soft-deleted), recent repositories (5), “Tambah Repository” quick action. No charts. - Repository list (read-only for now)
/admin/repositories:RepositoryTablewith the FR-008 columns, search, status filter, pagination,PublicationStatusBadge. - Category management
/admin/categories(FR-011): list with repository counts, create/editCategoryForm(dialog), delete withConfirmDeleteDialog. Blocked when in use, with an explanatory message. Case-insensitive unique name, unique slug,requireAdmin()in every action, cache revalidation.
7.2 Deliverables & exit criteria
Section titled “7.2 Deliverables & exit criteria”- The seeded admin can log in and log out. A wrong password and an unknown email produce the same message.
- After 5 failed attempts, further attempts are blocked for the window.
- Every
/admin/*route redirects anonymous users. Calling each admin server action directly without a session returnsUNAUTHORIZED(integration test). - After logout, a previously copied session cookie no longer grants access.
- Category CRUD works, the duplicate name “web application” vs “Web Application” is rejected, and deleting an in-use category is blocked.
8. Phase 4 — Repository CRUD & Media
Section titled “8. Phase 4 — Repository CRUD & Media”Goal: the admin can publish real repository content without code changes (PRD FR-008 to FR-010, §9, §10.3–10.4).
8.1 Tasks
Section titled “8.1 Tasks”- Storage
-
lib/storage/s3-adapter.ts(put, delete,publicUrl) configured purely by env and working with MinIO, R2 and S3. -
lib/storage/image-processing.ts: magic-byte sniff (JPEG/PNG/WebP),sharpdecode with a pixel limit, EXIF strip, max 2560 px, WebP re-encode, dimensions. -
lib/storage/keys.ts: server-generatedrepositories/{yyyy}/{mm}/{uuid}.webp. -
lib/storage/media-service.ts:processUpload,attachUploads(ownership + kind + unattached-or-same-repo checks),detachAndDeleteafter commit.
-
- Upload endpoint
POST /api/uploads:requireAdmin(), Origin check,Content-Lengthpre-check,UPLOAD_MAX_BYTES,kindparam,media_uploadsinsert, returns{uploadId, url, width, height}. Plus aremoveUploadserver action for pending uploads (PRDuploadRepositoryImage/removeRepositoryImage). - Validation
lib/validations/repository.ts:repositoryDraftSchemaandrepositoryPublishSchema(title 3–120, slug kebab-case, short description 10–300, valid category, overview non-empty, developer name, cover, ≥ 1 and ≤ 10 screenshots, http/https URLs only, array caps). SharedsafeUrlandslughelpers. - Admin service
lib/repositories/admin-service.ts:getAdminRepositoryList,getAdminRepositoryById,createRepository,updateRepository,deleteRepository(soft, unfeatures),updatePublicationStatus(completeness check in the transaction,published_aton first publish),updateFeaturedStatus. Every write recomputessearch_text, sanitizesoverviewand revalidates tags. - Server actions
lib/actions/repository-actions.ts: thin wrappers that callrequireAdmin(), parse with Zod, call the service and returnActionResult. RepositoryForm(shared by new/edit, RHF + Zod resolver), with the 6 sections of FR-009:- A: title → auto slug (editable, with a warning when changing the slug of a published item), short description with a counter, category select, tags multi-input.
- B:
RichTextEditor(Tiptap: paragraph, H2/H3, bold, italic, bullet/numbered list, link with URL validation), repeatable key features, tech stack multi-input. - C: developer name, information, website.
- D: product, source code and demo URLs.
- E:
ImageUploader(cover, banner) andScreenshotManager(multi-upload, previews, progress, remove, dnd-kit reorder with keyboard support, max 10). - F: status, featured, release date. Actions: Save as Draft, Publish Repository, Cancel (confirms if the form has unsaved changes).
- Field-level errors from the server mapped back into the form (
FormErrorMessage). After publishing, a success toast with a link to the public page.
- Pages:
/admin/repositories/new,/admin/repositories/[id]/edit(404 for unknown or deleted ids). Tiptap and dnd-kit are loaded only in admin bundles. - Table actions (FR-008): publish/unpublish, feature/unfeature (optimistic + toast), edit, delete with
ConfirmDeleteDialog. - Maintenance scripts:
scripts/media-cleanup.ts(orphans > 24 h, stale rate-limit rows) andscripts/repositories-purge.ts(soft-deleted pastREPOSITORY_RETENTION_DAYS). Both have dry-run by default and--apply.
8.2 Deliverables & exit criteria
Section titled “8.2 Deliverables & exit criteria”- Flow B (PRD §13) works end to end: the draft is saved with partial data, then published once complete, and appears on
/,/repositories, the category page and its own detail page within one request after the save. - Publishing an incomplete repository is rejected with field-level errors (missing cover, zero screenshots, and so on).
- Uploading a
.png-renamed.exe, an SVG, a 6 MB image or an 11th screenshot is rejected with a clear message. - A failed upload or save during edit leaves the existing images intact (FR-010).
- Reorder persists and is reflected in the public gallery. Featured toggling updates the homepage carousel.
- Deleted repositories disappear publicly, their media is retained per policy, and the purge script removes them after retention.
- Overview containing
<script>,onerror=, orjavascript:links is stored and rendered safely.
9. Phase 5 — QA, SEO & Production Readiness
Section titled “9. Phase 5 — QA, SEO & Production Readiness”Goal: the application is verified against PRD §19 and §20 and ready to deploy.
9.1 Tasks
Section titled “9.1 Tasks”- SEO (§11)
-
generateMetadataon the detail and category pages: unique title ({title} | Soedirman Digital Repository), meta description, canonical, Open Graph title, description and image (cover). Site-level defaults in the root layout. -
app/sitemap.ts(published only,lastModified = updated_at),app/robots.ts(disallow/admin,/api),noindexon the admin layout, usefulnot-found.tsx. - Semantic headings (one
h1per page), descriptive alt text.
-
- Security hardening (§10)
- Security headers and CSP in
next.config.ts. Verify that no inline-script breakage occurs. - Confirm
error.tsxand production responses hide stack traces. - Secret-leak check: build, then grep
.next/staticfor env secret values. - Dependency audit (
npm audit --omit=dev).
- Security headers and CSP in
- Automated tests (§19)
- Unit: schemas, safe URL, sanitizer, slugify, search text, image sniffing, rate limit.
- Integration: public visibility rules, admin action authorization (all actions, anonymous →
UNAUTHORIZED), publish completeness, media ownership, category constraints. - E2E (Playwright): every scenario in PRD §19 Public, Admin and Security, on desktop and mobile viewports, plus an axe scan of the main pages.
- Performance (§12)
- Lighthouse on a production build (home, catalog, detail): Performance ≥ 90, Accessibility ≥ 90, CLS ≤ 0.1. Fix image sizing, LCP priority and client bundle size.
- Verify there are no client-side data waterfalls on public pages (all data fetched in RSC).
- Production preparation
- Production env checklist, bucket CORS/public-read policy,
AUTH_TRUST_HOST/AUTH_URL, HTTPS. - Optional
output: "standalone"Dockerfile if the VPS target is chosen. - Migration deploy procedure (
prisma migrate deploy), first-admin seeding procedure, maintenance script scheduling.
- Production env checklist, bucket CORS/public-read policy,
- Documentation
-
README.md: setup, environment variables, migration, seed, development, testing, deployment (§21.19). -
docs/DEPLOYMENT.md: target-specific runbook, backup/restore notes, retention policy.
-
9.2 Deliverables & exit criteria
Section titled “9.2 Deliverables & exit criteria”- PRD §20 Definition of Done items 1–15 each verified, with evidence recorded in a checklist.
- All test suites are green and
npm run buildsucceeds from a clean clone.
10. Requirements Traceability
Section titled “10. Requirements Traceability”| PRD item | Phase | Primary artifacts |
|---|---|---|
| §2.3 Auth rules | 1 (seed), 3 | prisma/seed.ts, lib/auth/* |
| §3 Design system | 2 | globals.css, components/ui |
| FR-001 Homepage | 2 | app/(public)/page.tsx, FeaturedCarousel |
| FR-002 Catalog | 2 | app/(public)/repositories/page.tsx |
| FR-003 Detail | 2 (UI), 4 (real data) | app/(public)/repositories/[slug] |
| FR-004 Categories | 2 | app/(public)/categories/[slug] |
| FR-005 Search | 2 | GlobalSearch, search_text |
| FR-006 Login | 3 | app/admin/(auth)/login, lib/auth |
| FR-007 Dashboard | 3 | app/admin/(dashboard)/page.tsx |
| FR-008 Repo management | 3 (list), 4 (actions) | RepositoryTable |
| FR-009 / FR-010 Create/Edit | 4 | RepositoryForm, /api/uploads |
| FR-011 Category mgmt | 3 | app/admin/(dashboard)/categories |
| §7 Database | 1 | prisma/* |
| §9 Server operations | 2 (public), 3–4 (admin) | lib/repositories/*, lib/actions/* |
| §10 Security | 3–5 | see PROJECT_ARCHITECTURE §8 |
| §11 SEO | 5 (basic metadata already in 2) | generateMetadata, sitemap.ts, robots.ts |
| §12 Performance | 2 (practices), 5 (verification) | next/image, caching |
| §19 Tests | 1 (scaffold), 3–5 | tests/* |
| §21.19 README | 1 (initial), 5 (final) | README.md |
11. Security Considerations (summary)
Section titled “11. Security Considerations (summary)”The full control matrix is in PROJECT_ARCHITECTURE.md §8.
- Authorization lives in the server action and handler, not in the proxy. This is tested by calling every action anonymously.
- Revocable sessions: JWT plus
session_versionDB check. Logout and password change invalidate tokens. - Brute-force protection: DB-backed per-IP and per-email limiter, generic errors, dummy hash verify.
- Stored XSS: overview allow-list sanitized on write and on render. Every other field is plain text.
- Unsafe URLs: http/https only, enforced server-side. External links get
noopener noreferrer. - Uploads: size cap before buffering, magic-byte check, sharp re-encode to WebP, server keys, no SVG, ownership ledger.
- Draft confidentiality: one public query module with a hard-coded filter. Drafts are excluded from sitemap and metadata.
- Secrets: env-only,
server-onlymodules, noNEXT_PUBLIC_secrets,.envgit-ignored, no default production credentials. - Transport and headers: HTTPS, HSTS, nosniff, frame-ancestors none, Referrer-Policy, Permissions-Policy, CSP.
- Error hygiene: generic messages to users, detailed logs on the server only.
12. Technical Risk Register
Section titled “12. Technical Risk Register”| ID | Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|---|
| R-1 | Brief/workspace mismatch: the claimed scaffold does not exist | Confirmed | Medium | Phase 1 includes scaffolding. Confirm there is no other source of the “existing setup”. |
| R-2 | Auth.js v5 is still on the beta npm tag |
Medium | Medium | Pin the exact version. Keep all Auth.js usage behind lib/auth/* so it can be swapped. Covered by integration and E2E tests. |
| R-3 | JWT sessions are not revocable by default (conflicts with §10.1) | High if ignored | High | session_version DB check in requireAdmin(). |
| R-4 | Prisma 7 changes (ESM-only, mandatory driver adapter, prisma.config.ts, custom output path) |
Medium | Medium | Follow the v7 setup exactly in Phase 1 and validate build, seed and tests early. |
| R-5 | Custom SQL indexes (trigram, partial, lower(name)) drift or get dropped by later migrations |
Medium | Medium | Review every generated migration. Add an integration test that asserts the indexes exist. |
| R-6 | Orphaned or lost media from upload-before-save | Medium | Low–Medium | media_uploads ledger, delete only after commit, cleanup script. |
| R-7 | Request-body limits on serverless hosts (about 4.5 MB on Vercel) vs the 5 MB upload cap | Medium (host-dependent) | Medium | Confirm the host before Phase 4. Set UPLOAD_MAX_BYTES accordingly, or use presigned-to-quarantine + server validation. |
| R-8 | CSP vs Next.js inline scripts: strict nonce CSP forces dynamic rendering and hurts caching | Medium | Low–Medium | Start with a CSP that does not use nonces (strict img-src, frame-ancestors, object-src 'none') and document the trade-off. |
| R-9 | Lighthouse ≥ 90 is at risk with large hero images, the carousel and the Tiptap bundle | Medium | Medium | WebP re-encoding, stored dimensions, sizes, LCP priority, admin-only dynamic imports, measure in Phase 2 and 5. |
| R-10 | Path with spaces on Windows (Mini MBA) breaks some scripts or native tools |
Medium | Low | Quote paths in scripts, verify sharp, @node-rs/argon2 and Prisma in Phase 1. Docker volumes use relative paths. |
| R-11 | Native modules (sharp, @node-rs/argon2) behave differently on the Windows dev machine and the Linux prod host |
Low–Medium | Medium | Use prebuilt binaries. Install in the target environment (do not copy node_modules). Run the Docker build in CI. |
| R-12 | IP spoofing through X-Forwarded-For weakens the per-IP rate limit |
Medium | Low | Trust the forwarded header only behind a known proxy. The per-email limiter is independent of IP. |
| R-13 | Slug edits on published items break shared links | Medium | Low | UI warning. Redirects are out of MVP scope (would be a P1 discussion). |
| R-14 | Visual design too close to Steam (trademark/trade dress) | Low | Medium | Use only the patterns and palette from the PRD. Original logo and assets, no Steam names or imagery. |
| R-15 | Timezone confusion (UTC storage vs WIB display) | Medium | Low | TIMESTAMPTZ everywhere. One formatDate() helper fixed to Asia/Jakarta and id-ID. |
| R-16 | Demo data leaking to production | Low | Medium | Seed guards (NODE_ENV, SEED_DEMO_DATA), “[DEMO]” marker, production checklist item. |
13. Open Decisions (inputs needed)
Section titled “13. Open Decisions (inputs needed)”| # | Question | Default if unanswered | Needed by |
|---|---|---|---|
| Q-1 | Where is the “already initialized” setup, if anywhere other than this folder? | Treat as greenfield | Phase 1 start |
| Q-2 | Deployment target: VPS/container or Vercel-like serverless? | Node server (VPS/container) | Phase 4 |
| Q-3 | Object storage provider for production: Cloudflare R2 or AWS S3? | Cloudflare R2 | Phase 4 |
| Q-4 | Accept the PRD-aligned schema additions (DATABASE_DESIGN §9 D-5)? | Accept | Phase 1 |
| Q-5 | Category required for drafts (D-1), retention days (D-3), category delete with only soft-deleted references (D-2) | Required / 30 days / block until purge | Phase 1 |
| Q-6 | Official SDR logo/branding assets and the organization name for the footer | Text-based placeholder logo | Phase 2 |
| Q-7 | Production domain (canonical URLs, Auth URL) | Configured through env later | Phase 5 |
14. Next Concrete Step
Section titled “14. Next Concrete Step”Start Phase 1, task group 1–4. First confirm that the empty package.json can be removed (Q-1). Then:
git init+.gitignore.- Scaffold Next.js 16 (TypeScript, App Router, Tailwind v4, ESLint, no
src/, alias@/*) in place, keepingdocs/. - Add
docker-compose.yml(Postgres 17 + MinIO),.env.exampleandlib/env.ts. - Install Prisma 7 +
@prisma/adapter-pg, writeprisma.config.tsandschema.prismafrom DATABASE_DESIGN §6, and run the initial migration with the custom index SQL. - Write
prisma/seed.ts(categories + env-based Argon2id admin + dev-only demo data). - Verify:
npm run build,npm run db:migrate,npm run db:seed, and inspect the data in Prisma Studio.