ShipStation Portfolio Manager

Generate and manage personal portfolio websites through natural language prompts powered by Claude AI.

Overview

ShipStation is an AI-powered portfolio management service that enables users to create, edit, and deploy personal websites through a conversational interface. The platform leverages Claude AI to generate HTML/CSS/JavaScript code from natural language descriptions, providing real-time preview and version control.

Tech Stack

Instructions

1. Understanding the Project Structure

Before making changes, familiarize yourself with:

- `/pages/` - Main application routes (Home, Ship, Edit, Portfolio)

- `/components/` - Reusable UI components

- `/store/` - Redux slices for state management

- `/hooks/` - Custom React hooks (`useDisclosure`, `useProject`)

- `/lib/` - API clients and utilities

- `/controllers/` - HTTP request handlers

- `/services/` - Business logic and AI integration

- `/routes/` - API endpoint definitions

- `/config/tools/` - Structured AI tool configurations

- `/middleware/` - Express middleware (auth, error handling)

- Schema includes: `ships` (websites), `user_profiles`, `conversations`, `code_versions`

- Row-level security policies implemented

- Real-time subscriptions for live updates

2. Development Workflow

**Starting Development**:

```bash

Backend server (from root)

npm run dev

Frontend dev server (separate terminal)

cd client && npm run dev

```

**Code Quality**:

```bash

Lint backend

npm run lint

Lint frontend

cd client && npm run lint

```

**Building for Production**:

```bash

cd client && npm run build

npm start

```

3. Working with AI Generation

The core AI generation flow uses Anthropic Claude API:

When modifying AI generation:

1. Check existing tool definitions in `/server/config/tools/`

2. Update service layer methods in `/server/services/`

3. Ensure Socket.io events emit progress updates

4. Save generated code versions to database

4. Frontend State Management

The application uses Redux Toolkit with multiple slices:

When adding features:

1. Create or update Redux slices in `/client/src/store/`

2. Use custom hooks for component logic

3. Subscribe to Supabase real-time for live data

4. Handle loading and error states consistently

5. Database Operations

Supabase client is configured in both frontend and backend:

Always:

6. API Endpoints

Backend routes follow RESTful patterns:

When adding endpoints:

1. Define route in `/server/routes/`

2. Implement controller in `/server/controllers/`

3. Add business logic in `/server/services/`

4. Update frontend API client in `/client/src/lib/`

7. Environment Configuration

Multiple environment files are used:

Required variables:

8. Deployment

The application is deployed on Heroku:

Before deploying:

1. Build frontend: `cd client && npm run build`

2. Verify environment variables set on Heroku

3. Check Sentry configuration for error tracking

4. Test Socket.io connections work through load balancer

9. Testing Strategy

Before implementing tests:

10. Common Tasks

**Adding a New Feature**:

1. Plan data model changes (Supabase migrations)

2. Create backend API endpoints

3. Implement frontend UI components

4. Update Redux store if needed

5. Add real-time subscriptions for live updates

6. Test end-to-end flow

**Modifying AI Behavior**:

1. Update tool definitions in `/server/config/tools/`

2. Adjust service methods in `/server/services/`

3. Test with various prompts

4. Monitor token usage and costs

**Debugging Issues**:

1. Check Sentry for backend errors

2. Use browser DevTools for frontend issues

3. Verify Socket.io connections in Network tab

4. Review Supabase logs for database queries

5. Check environment variables are set correctly

Constraints

Key Files