{"id":50425356,"url":"https://github.com/taichi112/personal-profile-prototype","last_synced_at":"2026-05-31T10:02:53.838Z","repository":{"id":333282243,"uuid":"1136791569","full_name":"TaiChi112/Personal-Profile-Prototype","owner":"TaiChi112","description":"Personal-Profile-Prototype: A highly scalable CMS-style personal portfolio. Architected with 14+ Gang of Four (GoF) Design Patterns to systematically manage dynamic layouts, content hierarchies, themes, and complex workflows.","archived":false,"fork":false,"pushed_at":"2026-05-06T21:06:31.000Z","size":5156,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-06T22:28:42.836Z","etag":null,"topics":["blog-engine","design-patterns","nextjs","object-oriented-design","personal-website","portfolio","resume","typescript"],"latest_commit_sha":null,"homepage":"https://taichi112.works","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TaiChi112.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-18T11:16:06.000Z","updated_at":"2026-05-06T21:06:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/TaiChi112/Personal-Profile-Prototype","commit_stats":null,"previous_names":["taichi112/personal-website-prototype","taichi112/personal-profile-prototype"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/TaiChi112/Personal-Profile-Prototype","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TaiChi112%2FPersonal-Profile-Prototype","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TaiChi112%2FPersonal-Profile-Prototype/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TaiChi112%2FPersonal-Profile-Prototype/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TaiChi112%2FPersonal-Profile-Prototype/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TaiChi112","download_url":"https://codeload.github.com/TaiChi112/Personal-Profile-Prototype/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TaiChi112%2FPersonal-Profile-Prototype/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33726719,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blog-engine","design-patterns","nextjs","object-oriented-design","personal-website","portfolio","resume","typescript"],"created_at":"2026-05-31T10:02:52.903Z","updated_at":"2026-05-31T10:02:53.819Z","avatar_url":"https://github.com/TaiChi112.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Personal Profile Prototype\n\n\u003e **Version:** 0.1.0 (MVP) \u0026nbsp;|\u0026nbsp; **Status:** Active Development \u0026nbsp;|\u0026nbsp; **License:** Private\n\nA full-stack TypeScript/Next.js web application that serves as both an **interactive personal portfolio** and an **educational design pattern playground**. The system demonstrates all 23 Gang of Four (GoF) design patterns implemented within a production-grade architecture, targeting CS students, recruiters, and software engineering educators.\n\n---\n\n## Table of Contents\n\n1. [Planning](#1-planning)\n2. [Analysis](#2-analysis)\n3. [Design](#3-design)\n4. [Implementation](#4-implementation)\n5. [Testing](#5-testing)\n6. [Deployment](#6-deployment)\n7. [Maintenance](#7-maintenance)\n\n---\n\n## 1. Planning\n\n### 1.1 Problem Statement\n\nTraditional developer portfolios are static, single-purpose pages that fail to demonstrate **depth of software engineering knowledge**. Simultaneously, CS curricula often teach design patterns in isolation — without grounding them in real, working systems. This project resolves both problems by merging portfolio functionality with a living, interactive pattern showcase.\n\n### 1.2 Project Objectives\n\n| Objective | Description |\n|-----------|-------------|\n| **Portfolio Showcase** | Present projects, blog posts, resume, articles, and podcast content in a unified, dynamic interface |\n| **Pattern Playground** | Implement all 23 GoF design patterns as first-class, observable features of the running application |\n| **Educational Reference** | Provide a production-grade codebase that CS students and educators can study and extend |\n| **Future AI Integration** | Architect the system to support LLM-powered content generation and intelligent assistants |\n\n### 1.3 Technology Stack Rationale\n\n| Layer | Technology | Rationale |\n|-------|-----------|-----------|\n| **Frontend Framework** | Next.js 16 + React 19 | App Router support, SSR/CSR flexibility, API routes co-location |\n| **Language** | TypeScript 5.9 (strict) | Type safety essential for pattern demonstrations; generics power Strategy/Iterator/Composite |\n| **Styling** | Tailwind CSS 4 + PostCSS | Utility-first enables rapid theme switching; supports Abstract Factory theme families |\n| **Runtime Scripting** | Bun | Fast script execution for seeding, integration tests, and CI pipelines |\n| **ORM** | Prisma 7 | Type-safe database access; migration management for schema evolution |\n| **Database** | PostgreSQL 16 | ACID compliance; relational model suits User→Post ownership graph |\n| **Authentication** | NextAuth.js 4 | Pluggable OAuth providers; JWT session strategy with role augmentation |\n| **Containerization** | Docker + Docker Compose | Environment parity; isolates PostgreSQL; enables GCP Cloud Run deployment |\n| **CI/CD** | GitHub Actions | Automated lint → integration test → build → GCP deploy pipeline |\n\n### 1.4 Success Criteria (MVP)\n\n- [x] All 23 GoF patterns implemented in `src/patterns/` with 140+ test cases\n- [x] Functional portfolio sections: Projects, Blog, Resume, Articles, Podcast, Contact, Dashboard\n- [x] Working authentication (Google OAuth + test credentials)\n- [x] Theme customization (dark/light, 4 style families, 2 font families, EN/TH i18n)\n- [x] Guided tour system with iterator-driven step navigation\n- [x] Command palette (Ctrl+K) with undo/redo history\n- [x] Docker-containerized development and production environments\n- [x] GitHub Actions CI/CD with GCP Cloud Run deployment target\n- [ ] Performance benchmarks (FCP \u003c 2.5s, LCP \u003c 4.0s) — *In Progress*\n- [ ] Full WCAG 2.1 AA accessibility audit — *In Progress*\n\n---\n\n## 2. Analysis\n\n### 2.1 Functional Requirements\n\n| ID | Feature | Priority | Status |\n|----|---------|----------|--------|\n| FR-1 | Portfolio Content Management (Composite tree, multi-layout) | Critical | ✅ Implemented |\n| FR-2 | Unified Feed with Filter Chain + Sort Strategy | High | ✅ Implemented |\n| FR-3 | Role-Based Authentication (Google OAuth + Credentials) | Critical | ✅ Implemented |\n| FR-4 | Runtime Theme \u0026 Localization System (Abstract Factory) | High | ✅ Implemented |\n| FR-5 | Guided Tour System (Iterator + State Machine) | Medium | ✅ Implemented |\n| FR-6 | Command Palette with Undo/Redo (Command + Memento) | Medium | ✅ Implemented |\n| FR-7 | Podcast Player (Finite State Machine) | Low | ✅ Implemented |\n| FR-8 | Contact Form with Mediator Validation | Medium | ✅ Implemented |\n| FR-9 | Admin Dashboard (Visitor analytics, Prototype cloning) | High | ✅ Implemented |\n| FR-10 | REST API for Posts CRUD | High | ✅ Implemented |\n| FR-11 | Full CRUD for Projects, Articles, Podcasts | Medium | 🔲 Planned |\n| FR-12 | AI/LLM Content Generation | Low | 🔲 Planned |\n\n### 2.2 Non-Functional Requirements\n\n| Requirement | Target | Status |\n|-------------|--------|--------|\n| First Contentful Paint (FCP) | \u003c 2.5s | To be defined |\n| Largest Contentful Paint (LCP) | \u003c 4.0s | To be defined |\n| Accessibility (WCAG) | 2.1 AA | To be defined |\n| Browser Support | Chrome, Firefox, Safari, Edge (latest 2) | Partial |\n| Mobile Responsiveness | 320px – 2560px | Partial |\n| Uptime Target | ≥ 99.5% | To be defined |\n| API Error Rate | \u003c 0.1% | To be defined |\n| TypeScript Strict Mode | 100% | ✅ Enforced |\n\n### 2.3 Stakeholders \u0026 User Roles\n\n| Role | Capabilities |\n|------|-------------|\n| **Guest** | View public portfolio sections, browse content feed |\n| **Viewer** | All guest permissions + filter/sort feed, access guided tour, use command palette |\n| **Admin** | All viewer permissions + create/delete posts, clone project templates, view dashboard analytics |\n\n---\n\n## 3. Design\n\n### 3.1 Architectural Style\n\nThe system follows a **Pattern-Driven UI Monolith** with a **Layered Architecture** within a single Next.js application:\n\n```mermaid\nblock-beta\n  columns 1\n\n  block:client[\"Client (Browser)\"]\n    columns 1\n    ui[\"🖥️ UI Layer — React Components\\nNavigationShell · Sections · Feed · System Controls\"]\n    domain[\"⚙️ Domain Layer — Models \u0026 Services\\nTheme · Command · Feed · Content · Tour\"]\n    facade[\"🏛️ Application Facade\\nAppSystemFacade (Bootstrap)\"]\n  end\n\n  arrow[\"HTTP / JSON\"]\n\n  block:server[\"Server (Next.js)\"]\n    columns 1\n    api[\"🌐 Server Layer — Next.js API Routes\\n/api/auth · /api/posts · Auth Middleware\"]\n    dal[\"🔗 Data Access Layer — Prisma ORM\"]\n    db[\"🗄️ Database — PostgreSQL 16\\nusers · posts · future models\"]\n  end\n\n  ui --\u003e domain\n  domain --\u003e facade\n  facade --\u003e arrow\n  arrow --\u003e api\n  api --\u003e dal\n  dal --\u003e db\n```\n\n### 3.2 Design Patterns Implemented\n\nAll **23 Gang of Four** patterns are implemented and observable in the running application.\n\n#### Creational (5)\n\n| Pattern | Implementation | Location |\n|---------|---------------|----------|\n| **Singleton** | `NotificationService`, `ToastEventEmitter`, `CommandHistory` | `app/services/system/` |\n| **Factory Method** | `LocalizationFactory` — creates EN/TH locale objects | `app/models/theme/` |\n| **Abstract Factory** | `StyleFactory` — creates Modern/Minimal/Future/Academic theme families | `app/models/theme/` |\n| **Builder** | `ContentBuilder` — fluent API for constructing nested content trees | `app/models/` |\n| **Prototype** | `ProjectTemplate` + `ProjectTemplateRegistry` — admin template cloning | `app/models/template/` |\n\n#### Structural (7)\n\n| Pattern | Implementation | Location |\n|---------|---------------|----------|\n| **Adapter** | `adaptBlogToUnified`, `adaptProjectToUnified` — normalize diverse content types | `app/services/content/` |\n| **Bridge** | `NotificationService` + `INotificationChannel` — decouple notification logic from delivery | `app/services/system/` |\n| **Composite** | `LayoutNode` / `CompositeNode` / `LeafNode` — recursive content tree | `app/interfaces/content-tree.ts` |\n| **Decorator** | `ContentDecorator` — dynamically adds badges/overlays to feed cards | `app/components/feed/` |\n| **Facade** | `AppSystemFacade` — single entry point for app bootstrap and initialization | `app/services/system/` |\n| **Flyweight** | `ParticleFactory` — shared intrinsic state for animated background particles | `app/components/system/` |\n| **Proxy** | `AccessControlProxy` — gate premium/admin content behind session checks | `app/models/` |\n\n#### Behavioral (11)\n\n| Pattern | Implementation | Location |\n|---------|---------------|----------|\n| **Chain of Responsibility** | `FilterHandler` pipeline — Type → Tag → Search filters | `app/services/feed/` |\n| **Command** | `ICommand` + `NavigateCommand`, `ToggleThemeCommand`, etc. | `app/models/command/` |\n| **Iterator** | `TourIterator` — sequential step traversal for guided tour | `app/models/tour/` |\n| **Observer** | `ToastEventEmitter` — event-driven toast notification dispatch | `app/services/system/` |\n| **Strategy** | `FeedSortStrategy` — `DateSortStrategy`, `TitleSortStrategy`, `LengthSortStrategy` | `app/models/feed/` |\n| **State** | `AudioPlayerContext` with `StoppedState`, `PlayingState`, `PausedState` | `app/models/podcast/` |\n| **Template Method** | Content export algorithm with pluggable format steps | `src/patterns/` |\n| **Mediator** | `ContactFormMediator` — orchestrates form validation and submission | `app/services/contact/` |\n| **Memento** | `FeedStateMemento` + `FeedStateCaretaker` — snapshot/restore filter state | `app/models/feed/` |\n| **Interpreter** | Grammar evaluator for expression parsing | `src/patterns/` |\n| **Visitor** | `MetricsVisitor`, `TagsVisitor` — analytics traversal of content trees | `app/components/dashboard/` |\n\n### 3.3 Data Model\n\n```mermaid\nerDiagram\n    USER {\n        string id PK \"cuid\"\n        string email UK\n        string name\n        string image\n        string role\n        string provider\n        string providerAccountId\n        datetime createdAt\n        datetime updatedAt\n    }\n\n    POST {\n        string id PK \"cuid\"\n        string title\n        string content\n        boolean published\n        string authorId FK\n        datetime createdAt\n        datetime updatedAt\n    }\n\n    USER ||--o{ POST : \"authors\"\n```\n\n| Entity | Fields | Notes |\n|--------|--------|-------|\n| `User` | `id` (cuid PK), `email` (unique), `name`, `image`, `role`, `provider`, `providerAccountId`, `createdAt`, `updatedAt` | Composite unique on `[provider, providerAccountId]` |\n| `Post` | `id` (cuid PK), `title`, `content`, `published`, `authorId` (FK → User), `createdAt`, `updatedAt` | Index on `authorId` |\n\n**Planned models:** `Project`, `Article`, `Podcast`, `Blog`, `Template`, `Tag`, `Category`\n\n### 3.4 Authentication \u0026 Authorization Flow\n\n```mermaid\nflowchart TD\n    A([\"🔑 Login\"]) --\u003e B{\"Choose Provider\"}\n    B -- \"Google OAuth\" --\u003e C[\"NextAuth OAuth Callback\"]\n    B -- \"Credentials\" --\u003e D[\"Credential Validation\"]\n    C --\u003e E[\"Upsert User in PostgreSQL\"]\n    D --\u003e E\n    E --\u003e F[\"Generate JWT\\n(userId + role)\"]\n    F --\u003e G[\"Session Callback\\naugments session object\"]\n    G --\u003e H{\"Access Protected Route?\"}\n    H -- \"Yes\" --\u003e I[\"requireAdminSession()\"]\n    H -- \"No\" --\u003e K[\"Render Viewer UI\"]\n    I -- \"Admin role\" --\u003e J[\"Render Admin UI\"]\n    I -- \"Insufficient role\" --\u003e L([\"401 Unauthorized\"])\n```\n\n---\n\n## 4. Implementation\n\n### 4.1 Directory Structure\n\n```\npersonal-profile-prototype/\n├── app/                        # Next.js App Router root\n│   ├── api/                    # Server-side API route handlers\n│   │   ├── auth/               # NextAuth.js endpoints\n│   │   ├── posts/              # Posts CRUD (GET, POST, DELETE)\n│   │   └── users/              # User management [planned]\n│   ├── components/             # Reusable React UI components\n│   │   ├── content/            # Content node renderers\n│   │   ├── dashboard/          # Metrics, tag cloud, analytics\n│   │   ├── feed/               # Feed cards, filters, sort bar\n│   │   ├── layout/             # Navigation shell, page structure\n│   │   ├── section/            # Section primitive wrappers\n│   │   └── system/             # Theme controls, tour, command palette, particles\n│   ├── features/               # Feature-level compositions\n│   │   ├── composition/        # Root app assembly (PersonalWebsiteApp)\n│   │   └── sections/           # Full section implementations\n│   ├── interfaces/             # TypeScript interface contracts\n│   │   ├── content-tree.ts     # IContentNode, IVisitor, IComponent\n│   │   └── feed.ts             # IFeedItem, IFeedState, ISortStrategy\n│   ├── lib/                    # Server-side utilities\n│   │   ├── auth.ts             # NextAuth configuration\n│   │   ├── prisma.ts           # Prisma singleton client\n│   │   └── require-admin-session.ts  # Auth middleware helper\n│   ├── models/                 # Domain model implementations\n│   │   ├── command/            # ICommand + concrete commands\n│   │   ├── feed/               # Sort strategies, Memento, FilterHandler\n│   │   ├── podcast/            # AudioPlayerContext + State classes\n│   │   ├── template/           # ProjectTemplate, registry (Prototype)\n│   │   ├── theme/              # Style/Font/Locale factories\n│   │   └── tour/               # TourIterator, tour steps\n│   ├── services/               # Business logic \u0026 orchestration\n│   │   ├── contact/            # ContactFormMediator\n│   │   ├── content/            # Content adapters, decorators\n│   │   ├── feed/               # Feed operations\n│   │   └── system/             # AppSystemFacade, NotificationService\n│   ├── data/                   # Static/mock data\n│   │   ├── content.ts          # Portfolio content seed\n│   │   └── resume.ts           # Resume data model\n│   ├── [tab]/                  # Dynamic tab routing\n│   ├── globals.css             # Global base styles\n│   ├── layout.tsx              # Root layout (Geist fonts, Providers)\n│   ├── page.tsx                # Root entry point\n│   └── providers.tsx           # React context providers (NextAuth SessionProvider)\n├── src/                        # Standalone pattern library\n│   ├── patterns/               # All 23 GoF patterns (standalone TypeScript)\n│   │   ├── 01_singleton_notifications.ts\n│   │   ├── ...\n│   │   ├── 24_visitor_operations.ts\n│   │   ├── TESTS.ts            # 30+ creational tests (Bun:test)\n│   │   ├── STRUCTURAL_TESTS.ts # 50+ structural tests\n│   │   ├── BEHAVIORAL_TESTS.ts # 60+ behavioral tests\n│   │   └── index.ts            # Central pattern exports\n│   ├── main.ts                 # Pattern library entry\n│   ├── interface.ts            # Shared type contracts\n│   └── data.ts                 # Shared mock data\n├── prisma/\n│   ├── schema.prisma           # Prisma data model\n│   └── migrations/             # Versioned schema migrations\n├── scripts/\n│   ├── integration-auth-db.ts  # Auth + DB integration test\n│   ├── integration-http-crud.ts        # HTTP CRUD integration test\n│   ├── integration-http-admin-users.ts # Admin endpoint integration test\n│   ├── prisma-crud-example.ts  # Prisma CRUD reference\n│   ├── deploy-gcp.sh           # Manual GCP deploy script\n│   └── setup-docker-dev.sh     # Docker dev environment setup\n├── lib/\n│   └── prisma.ts               # Root Prisma singleton (for scripts)\n├── .github/workflows/\n│   ├── ci.yml                  # CI: lint → migrate → seed → integration tests → build\n│   ├── deploy-gcp.yml          # CD: Docker build → GCR push → Cloud Run deploy\n│   └── codeql.yml              # CodeQL security scanning\n├── Dockerfile                  # Multi-stage production build\n├── docker-compose.yml          # Dev: PostgreSQL + Next.js app\n├── docker-compose.prod.yml     # Production compose configuration\n└── package.json                # Dependencies + npm scripts\n```\n\n### 4.2 Core API Endpoints\n\n| Method | Endpoint | Auth | Description |\n|--------|----------|------|-------------|\n| `GET` | `/api/auth/session` | Public | Check active session |\n| `POST` | `/api/auth/signin` | Public | NextAuth sign-in |\n| `POST` | `/api/auth/signout` | Session | Sign out |\n| `GET` | `/api/posts` | Session | List all posts |\n| `POST` | `/api/posts` | Admin | Create a new post |\n| `GET` | `/api/posts/[id]` | Session | Get single post |\n| `DELETE` | `/api/posts/[id]` | Admin | Delete a post |\n\n### 4.3 Naming Conventions\n\n| Construct | Convention | Example |\n|-----------|-----------|---------|\n| React Components | PascalCase | `UnifiedFeedSection`, `CommandPalette` |\n| Files | kebab-case | `feed-item-card.tsx` |\n| Interfaces | PascalCase (prefixed `I`) | `ICommand`, `IVisitor` |\n| Services | PascalCase + `Service` suffix | `NotificationService` |\n| Constants | UPPER_SNAKE_CASE | `MOCK_PROJECTS`, `LOCALES` |\n| Types | PascalCase | `DecorationType`, `LayoutStyleType` |\n\n### 4.4 Key Design Decisions\n\n- **React Context API** is used for global state (theme, language, admin role) rather than a third-party store — keeping the pattern surface visible without framework magic.\n- **Singleton services** are instantiated once at module load, ensuring pattern correctness is observable at runtime.\n- **Bun** is used as the script runner for seeding and integration tests in CI, while `npm`/Node.js remains the primary application runtime for Docker compatibility.\n- **Static mock data** (`app/data/`) drives the portfolio sections in the MVP; the REST API layer is designed to replace this data source as database models are added.\n\n---\n\n## 5. Testing\n\n### 5.1 Current Coverage\n\n| Layer | Framework | Status |\n|-------|-----------|--------|\n| **Pattern Unit Tests** | Bun (`bun:test`) | ✅ 140+ test cases across all 23 patterns |\n| **Integration — Auth + DB** | Bun script (`scripts/integration-auth-db.ts`) | ✅ Automated in CI |\n| **Integration — HTTP CRUD** | Bun script (`scripts/integration-http-crud.ts`) | ✅ Automated in CI |\n| **Integration — Admin Users** | Bun script (`scripts/integration-http-admin-users.ts`) | ✅ Automated in CI |\n| **Unit Tests — React Components** | Jest / React Testing Library | 🔲 To be defined |\n| **E2E Tests** | Playwright | 🔲 To be defined |\n\n### 5.2 Running Pattern Tests\n\n```bash\n# Creational patterns\nbun test src/patterns/TESTS.ts\n\n# Structural patterns\nbun test src/patterns/STRUCTURAL_TESTS.ts\n\n# Behavioral patterns\nbun test src/patterns/BEHAVIORAL_TESTS.ts\n\n# All patterns\nbun test src/patterns/\n```\n\n### 5.3 Running Integration Tests\n\n```bash\n# Prerequisites: database running and migrations applied\nnpm run db:up\nnpx prisma migrate deploy\n\n# Auth + database\nnpm run integration:auth-db\n\n# HTTP CRUD endpoints\nnpm run integration:http-crud\n\n# Admin user management\nnpm run integration:http-admin-users\n```\n\n### 5.4 Recommended Future Testing Strategy\n\n```\nUnit Tests (Jest + RTL)\n├── ContentBuilder.test.ts\n├── FeedStateMemento.test.ts\n├── AudioPlayerStateMachine.test.ts\n├── NotificationService.test.ts\n└── Adapters (adaptBlogToUnified, etc.)\n\nE2E Tests (Playwright)\n├── Portfolio viewing flow\n├── Feed filter → sort → display\n├── Theme switching (dark/light, styles)\n├── Authentication + admin feature gates\n└── Contact form submission\n```\n\n**Target coverage:** 80% for critical paths, 60% overall.\n\n---\n\n## 6. Deployment\n\n### 6.1 Prerequisites\n\n- Node.js 18+\n- Docker \u0026 Docker Compose\n- Bun (for scripts and CI)\n- Google Cloud SDK (for GCP deployment)\n\n### 6.2 Local Development\n\n```bash\n# 1. Clone the repository\ngit clone \u003crepository-url\u003e\ncd personal-profile-prototype\n\n# 2. Install dependencies (Bun lock file present)\nbun install\n# or: npm install\n\n# 3. Configure environment\ncp .env.example .env\n\n# 4. Start PostgreSQL\nnpm run db:up               # docker compose up -d\n\n# 5. Apply database migrations\nnpx prisma migrate dev\n\n# 6. Seed the database\nnpm run prisma:seed\n\n# 7. Start development server\nnpm run dev                 # Webpack dev server → http://localhost:3000\n# or: npm run dev:turbo     # Turbopack (faster, experimental)\n```\n\n### 6.3 Required Environment Variables\n\n```env\n# Database\nDATABASE_URL=postgresql://user:password@localhost:5432/personal_profile_prototype\n\n# NextAuth\nNEXTAUTH_URL=http://localhost:3000\nNEXTAUTH_SECRET=\u003crandom-256-bit-secret\u003e\n\n# Google OAuth (optional for dev)\nGOOGLE_CLIENT_ID=\u003cgcp-oauth-client-id\u003e\nGOOGLE_CLIENT_SECRET=\u003cgcp-oauth-client-secret\u003e\n\n# Test credentials (dev/staging only)\nADMIN_TEST_EMAIL=admin@example.com\nADMIN_TEST_PASSWORD=admin123\nVIEWER_TEST_PASSWORD=viewer123\n\n# App\nNODE_ENV=development\nNEXT_PUBLIC_API_URL=http://localhost:3000\n```\n\n### 6.4 Docker Production Build\n\n```bash\n# Build image\ndocker build -t personal-profile:0.1.0 .\n\n# Run with production env\ndocker run -p 3000:3000 --env-file .env.production personal-profile:0.1.0\n\n# Or use production compose\ndocker compose -f docker-compose.prod.yml up -d\n```\n\nThe Dockerfile uses a **multi-stage build**:\n- **Stage 1 (builder):** `node:18-alpine` — installs deps, generates Prisma client, builds Next.js\n- **Stage 2 (production):** `node:18-alpine` — copies built assets only, runs as non-root user `nextjs`\n\n### 6.5 CI/CD Pipeline\n\n```mermaid\nflowchart TD\n    A([\"📦 Push to main / PR Opened\"]) --\u003e B\n\n    subgraph CI [\"🔄 ci.yml — GitHub Actions\"]\n        direction TB\n        B[\"1. Setup Bun\"] --\u003e C[\"2. bun install --frozen-lockfile\"]\n        C --\u003e D[\"3. prisma generate\"]\n        D --\u003e E[\"4. prisma migrate deploy\\n(ephemeral PostgreSQL service)\"]\n        E --\u003e F[\"5. prisma seed\"]\n        F --\u003e G[\"6. integration:auth-db\"]\n        G --\u003e H[\"7. bun run build\"]\n        H --\u003e I[\"8. Start dev server\\n→ wait for /api/auth/session\"]\n        I --\u003e J[\"9. integration:http-crud\"]\n        J --\u003e K[\"10. integration:http-admin-users\"]\n    end\n\n    K --\u003e L{\"Push to\\nmain / staging?\"}\n    L -- \"No\" --\u003e M([\"✅ CI Complete\"])\n    L -- \"Yes\" --\u003e N\n\n    subgraph CD [\"🚀 deploy-gcp.yml — GitHub Actions\"]\n        direction TB\n        N[\"1. Authenticate to GCP\\n(Workload Identity Federation)\"] --\u003e O[\"2. docker build\\n→ tag with git SHA + latest\"]\n        O --\u003e P[\"3. docker push\\n→ Google Container Registry (gcr.io)\"]\n        P --\u003e Q[\"4. gcloud run deploy\\n→ Cloud Run (us-central1)\\n--set-secrets from Secret Manager\"]\n        Q --\u003e R[\"5. gcloud run services describe\\n→ output live URL\"]\n    end\n\n    R --\u003e S([\"🌐 Live on Cloud Run\"])\n```\n\n### 6.6 Deployment Targets\n\n| Environment | Platform | Trigger |\n|-------------|----------|---------|\n| **Development** | Local Docker Compose | Manual |\n| **Staging** | GCP Cloud Run (`staging` branch) | Push to `staging` |\n| **Production** | GCP Cloud Run (`prod`) | Push to `main` |\n\n---\n\n## 7. Maintenance\n\n### 7.1 Scalability\n\n- **Horizontal scaling:** GCP Cloud Run auto-scales container instances based on request load; stateless Next.js design supports this natively.\n- **Database scaling:** Migrate from single PostgreSQL container to GCP Cloud SQL with read replicas as traffic grows.\n- **Content volume:** The Composite tree and Adapter pattern ensure new content types can be added without modifying existing rendering logic.\n\n### 7.2 Monitoring \u0026 Logging\n\n| Area | Current | Planned |\n|------|---------|---------|\n| Client errors | `console.log` + Toast notifications | Sentry / GCP Error Reporting |\n| Server errors | Next.js default | Structured JSON logs → GCP Cloud Logging |\n| Performance | Manual | Core Web Vitals via Vercel Analytics or GCP |\n| Uptime | None | StatusPage.io / GCP Uptime Checks |\n| Analytics | `AnalyticsSystem` singleton (client-side) | Google Analytics / Plausible |\n\n### 7.3 Maintenance Schedule\n\n| Cadence | Task |\n|---------|------|\n| **Weekly** | Review CI failures; check error logs for patterns |\n| **Monthly** | `npm audit` + dependency security patches; analyze failed API requests |\n| **Quarterly** | Major framework version upgrades; security audit; load testing; DR drill |\n\n### 7.4 Disaster Recovery\n\n| Metric | Target |\n|--------|--------|\n| **RTO** (Recovery Time Objective) | 4 hours |\n| **RPO** (Recovery Point Objective) | 1 hour |\n| **Backup Strategy** | Daily automated PostgreSQL snapshots; weekly offsite |\n| **Rollback** | Cloud Run revision rollback via `gcloud run services update-traffic` |\n\n### 7.5 Future Enhancements\n\n- **AI-Native Content Generation:** Integrate an LLM API to auto-generate blog post drafts, project descriptions, and resume bullet points\n- **Database-backed portfolio:** Migrate static `data/content.ts` to Prisma-managed `Project`, `Article`, `Podcast`, and `Template` models\n- **Full-text search:** Add PostgreSQL full-text search or Algolia for the content feed\n- **Accessibility audit:** Complete WCAG 2.1 AA remediation and add automated axe-core checks to CI\n- **Progressive Web App (PWA):** Add service worker and offline support via `next-pwa`\n- **Kubernetes manifests:** Add Helm chart for multi-region, production-scale deployment\n\n---\n\n## Quick Reference: npm Scripts\n\n```bash\nnpm run dev                         # Start Webpack dev server\nnpm run dev:turbo                   # Start Turbopack dev server\nnpm run build                       # Type-check + Next.js production build\nnpm run start                       # Start production server\nnpm run lint                        # ESLint\n\nnpm run db:up                       # docker compose up -d (PostgreSQL)\nnpm run db:down                     # docker compose down\nnpm run db:logs                     # Follow PostgreSQL container logs\n\nnpm run prisma:generate             # Generate Prisma client\nnpm run prisma:migrate:dev          # Apply migrations (dev)\nnpm run prisma:seed                 # Seed database via Bun\n\nnpm run integration:auth-db         # Auth + database integration test\nnpm run integration:http-crud       # HTTP CRUD integration test\nnpm run integration:http-admin-users # Admin users integration test\n```\n\n---\n\n*Generated from codebase analysis · April 2026 · Personal Profile Prototype v0.1.0*","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaichi112%2Fpersonal-profile-prototype","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftaichi112%2Fpersonal-profile-prototype","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaichi112%2Fpersonal-profile-prototype/lists"}