Portfolio Codebase Assistant

Expert assistant for working with Wilson's personal portfolio codebase built with Next.js 15.

Overview

This skill provides comprehensive guidance for developing and maintaining a Next.js 15 portfolio application featuring:

Architecture Understanding

Route Groups & Structure

The application uses Next.js App Router with organized route groups:

1. **Public Routes** (`app/(main)/`):

- Shared layout with Navbar, Footer, ChatBubble, ParticlesWrapper

- ChatBotProvider context wrapping

- Main portfolio pages (home, contact, etc.)

2. **Authentication Routes**:

- `/give-me-the-token` - Admin login page

- `/do-not-get-in-here` - JWT-protected admin area

3. **API Routes** (`app/api/`):

- `auth-token/` - JWT generation

- `chat/` - Chatbot with health endpoint

- `logout/` - Session cleanup

Internationalization System

When working with text content:

1. Check current locale implementation in `i18n/config.ts`

2. Add translations to BOTH `messages/en.json` AND `messages/es.json`

3. Use `getUserLocale()` from `i18n/services.ts` for locale detection

4. Ensure `NextIntlClientProvider` wraps any new client components needing translations

Development Workflow

Starting Development

```bash

npm run dev # Development with Turbopack

npm run lint # Check code quality

npm run build # Test production build

npm run prod # Build and start production

```

Adding New Features

1. **New Portfolio Section**:

- Create component in `components/`

- Add interface to `interfaces/` if needed

- Update content files in `content/`

- Add translations to both locale files

- Integrate into `app/(main)/` layout

2. **New Protected Route**:

- Create route in `app/do-not-get-in-here/`

- Verify middleware protection in `middleware.ts`

- Ensure JWT validation works

3. **New API Endpoint**:

- Add to `app/api/`

- Include error handling

- Document environment variables if needed

Authentication Flow

When modifying auth:

1. JWT tokens use `jose` library (NOT jsonwebtoken)

2. Secret comes from `JWT_SECRET` env variable

3. Token stored in `auth-token` cookie

4. Middleware checks token validity on protected routes

5. Invalid tokens redirect to `/give-me-the-token`

6. Admin password in `SECRET_PASS` env variable

Working with Chatbot

The chatbot has external dependencies:

1. Check health via `/api/chat/health` before displaying

2. State managed in `context/ChatBotProvider.tsx`

3. Use `useChatBot()` hook in components

4. External API configured via `NEXT_PUBLIC_API_URL`

5. Message interface defined in `interfaces/IMessage.ts`

Component Patterns

UI Components

Located in `components/ui/` (shadcn/ui New York style):

Animation Components

1. **Framer Motion**: Used throughout for page/element transitions

2. **Reveal.tsx**: Wrapper component for reveal animations

3. **ParticlesWrapper**: Opt-in animated background using tsparticles

4. **Typed.js**: Typewriter effects in hero sections

Data Display Components

Environment Variables

Required variables in `.env`:

```

JWT_SECRET=<secret-for-jwt-signing>

SECRET_PASS=<admin-password>

NEXT_PUBLIC_API_URL=<external-api-endpoint>

```

Always verify these exist when working with auth or external services.

Styling Guidelines

1. **Tailwind CSS v4** with PostCSS

2. Use design tokens consistently

3. Follow responsive design patterns in existing components

4. Leverage shadcn/ui components before creating custom ones

5. Apply animations thoughtfully using Framer Motion

Data Management

Content Files

Located in `content/`:

Interfaces

Located in `interfaces/`:

When adding data, follow existing schema patterns.

Utilities

Key helper functions in `utils/`:

Use these instead of reimplementing common functionality.

Important Constraints

1. **Always update both locale files** when adding text content

2. **Check chatbot health** before displaying chat interface

3. **Verify JWT_SECRET exists** before testing protected routes

4. **Use path alias** `@/*` for imports from project root

5. **Follow TypeScript strict mode** - no implicit any

6. **Test builds** before considering features complete

Debugging Tips

1. **i18n issues**: Check both locale JSON files for missing keys

2. **Auth failures**: Verify JWT_SECRET and cookie settings

3. **Chatbot unavailable**: Test `/api/chat/health` endpoint

4. **Build errors**: Run `npm run build` to catch TypeScript issues

5. **Styling issues**: Check Tailwind v4 syntax (differs from v3)

Next Steps When Stuck

1. Read existing component implementations for patterns

2. Check middleware.ts:1 for route protection logic

3. Review i18n/config.ts:1 for locale configuration

4. Examine context/ChatBotProvider.tsx:1 for state management

5. Look at components/ui/ for available base components