← back to Goodquestion

README.md

376 lines

# SWOT Analysis Platform

AI-Powered Local Business Viability Analysis using Claude and Model Context Protocol (MCP)

## Overview

This Next.js application provides comprehensive SWOT (Strengths, Weaknesses, Opportunities, Threats) analysis for local business ventures. It leverages AI workflows through Claude API and integrates with an MCP server for deep data synthesis from historical documents, business directories, and market reports.

## Features

### Core Analysis Components

- **Go/No-Go Scorecard**: Visual recommendation with overall viability score (0-100)
- **Detailed SWOT Analysis**: Color-coded cards showing strengths, weaknesses, opportunities, and threats
- **Historical Context**: Timeline visualization of key economic events and area trajectory charts
- **Market Deep Dive**:
  - Competitor mapping with distance and rating analysis
  - Market size breakdown (TAM/SAM/SOM)
  - 5-year income projections with optimistic/realistic/pessimistic scenarios
- **System Architecture Mind Map**: Interactive visualization of the platform's technical components
- **Action Plan**: Prioritized next steps with cost and time estimates

## Tech Stack

- **Framework**: Next.js 15.5.4 with React 19
- **Styling**: Tailwind CSS 3.4 + shadcn/ui 2.1
- **AI Integration**: Anthropic Claude Sonnet 4.5
- **Data Protocol**: Model Context Protocol (MCP)
- **Charts**: Recharts 2.12
- **Type Safety**: TypeScript 5.6
- **Deployment**: Vercel (recommended)

## Project Structure

```
goodquestion/
├── src/
│   ├── app/
│   │   ├── api/
│   │   │   ├── analyze/          # Main SWOT analysis endpoint
│   │   │   └── mcp/              # MCP search and fetch endpoints
│   │   ├── layout.tsx
│   │   ├── page.tsx              # Main dashboard
│   │   └── globals.css
│   ├── components/
│   │   ├── action-plan/          # Action plan components
│   │   ├── historical/           # Historical timeline & trajectory charts
│   │   ├── market/               # Market analysis visualizations
│   │   ├── mindmap/              # System architecture mind map
│   │   ├── swot/                 # SWOT scorecard and charts
│   │   └── ui/                   # Reusable UI components (shadcn)
│   ├── lib/
│   │   ├── ai-workflows.ts       # Claude AI integration workflows
│   │   ├── mcp-client.ts         # MCP server client
│   │   ├── mock-data.ts          # Sample data for development
│   │   └── utils.ts              # Utility functions
│   └── types/
│       └── swot.ts               # TypeScript type definitions
├── package.json
├── tsconfig.json
├── tailwind.config.ts
└── next.config.js
```

## Installation

### Prerequisites

- Node.js 18+ and npm/pnpm/yarn
- Anthropic API key
- MCP server setup (optional for development)

### Steps

1. **Clone the repository**
   ```bash
   cd /root/WebsitesMisc/goodquestion
   ```

2. **Install dependencies**
   ```bash
   npm install
   ```

3. **Set up environment variables**
   ```bash
   cp .env.example .env
   ```

   Edit `.env` and add your API keys:
   ```env
   ANTHROPIC_API_KEY=your_anthropic_api_key_here
   MCP_SERVER_URL=http://localhost:8000
   MCP_API_KEY=your_mcp_api_key_here
   ```

4. **Run development server**
   ```bash
   npm run dev
   ```

5. **Open in browser**
   Navigate to [http://localhost:3000](http://localhost:3000)

## MCP Server Setup

The MCP (Model Context Protocol) server provides access to local business data through vector search.

### Quick Setup with Python and FastMCP

```python
# mcp_server.py
from fastmcp import FastMCP
import chromadb

mcp = FastMCP("Local Business SWOT Data")

# Initialize vector database
client = chromadb.Client()
collection = client.create_collection("business_data")

@mcp.tool()
def search(query: str, limit: int = 10):
    """Search for relevant business documents"""
    results = collection.query(
        query_texts=[query],
        n_results=limit
    )
    return results

@mcp.tool()
def fetch(document_id: str):
    """Fetch full document by ID"""
    doc = collection.get(ids=[document_id])
    return doc

if __name__ == "__main__":
    mcp.run()
```

Run the server:
```bash
pip install fastmcp chromadb
python mcp_server.py
```

### Data Sources to Ingest

- Local business directories (Yelp, Google Business, Chamber of Commerce)
- Historical economic documents (PDFs, reports)
- Census and demographic data
- Zoning maps and regulatory documents
- Market trend reports

## AI Workflows

### SWOT Analysis Generation

The platform uses specialized AI workflows to generate comprehensive analysis:

```typescript
// Example usage
import { swotWorkflow } from '@/lib/ai-workflows'

const analysis = await swotWorkflow.generateAnalysis(
  'Artisan Coffee Roastery',
  'Specialty Coffee Shop',
  'Downtown Portland, OR'
)
```

### Workflow Steps

1. **Data Collection**: Query MCP server for competitors, historical data, market trends
2. **Document Retrieval**: Fetch full content of top relevant documents
3. **AI Analysis**: Claude processes data and generates structured SWOT output
4. **Response Parsing**: Convert AI response to typed TypeScript objects

## API Routes

### POST /api/analyze

Generate complete SWOT analysis for a business idea.

**Request:**
```json
{
  "businessName": "Artisan Coffee Roastery",
  "businessType": "Specialty Coffee Shop",
  "location": "Downtown Portland, OR"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "swotAnalysis": { /* Full SWOT data */ },
    "historicalContext": { /* Historical analysis */ }
  }
}
```

### POST /api/mcp/search

Search the MCP vector database.

**Request:**
```json
{
  "query": "coffee shops Portland",
  "filters": {
    "documentType": ["business-directory"],
    "location": "Portland, OR"
  },
  "limit": 10
}
```

### GET /api/mcp/fetch/[documentId]

Retrieve a specific document by ID.

## Deployment

### Vercel (Recommended)

1. **Install Vercel CLI**
   ```bash
   npm i -g vercel
   ```

2. **Deploy**
   ```bash
   vercel
   ```

3. **Set environment variables**
   In the Vercel dashboard, add:
   - `ANTHROPIC_API_KEY`
   - `MCP_SERVER_URL`
   - `MCP_API_KEY`

4. **Enable continuous deployment**
   Connect your GitHub repository for automatic deployments on push

### Alternative: Docker

```dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]
```

Build and run:
```bash
docker build -t swot-platform .
docker run -p 3000:3000 --env-file .env swot-platform
```

## Development Workflow

### Using Codex for Parallel Development

As outlined in the scaffolding document, you can use AI-powered development tools to build multiple UI variations:

```bash
# Generate 3 parallel versions
codex build --parallel 3 --from-prd product-requirements.md
```

This creates three distinct implementations that you can compare and merge.

### Testing with Mock Data

The application includes comprehensive mock data in `src/lib/mock-data.ts` for development without an MCP server. Replace this with real API calls in production.

## Customization

### Adding New Visualizations

1. Create component in appropriate directory (`src/components/`)
2. Define required props using types from `src/types/swot.ts`
3. Import and add to `src/app/page.tsx`

### Extending AI Workflows

Add new specialized agents in `src/lib/ai-workflows.ts`:

```typescript
export class CompetitorAnalysisWorkflow {
  async analyzeCompetitors(businessType: string, location: string) {
    // Custom analysis logic
  }
}
```

## Next Steps

Based on the action plan scaffolding:

1. **Buy Domain Name**: Secure `.com` and `.coffee` domains via Vercel Domains
2. **Set Up Production MCP Server**: Deploy to Replit or AWS Lambda
3. **Marketing Setup**: Configure Google Ads and local SEO
4. **Keyword Research**: Analyze advertising costs for target market
5. **A/B Testing**: Deploy multiple UI versions and track conversion

## Troubleshooting

### MCP Connection Issues

```bash
# Check if MCP server is running
curl http://localhost:8000/health

# Verify environment variables
echo $MCP_SERVER_URL
```

### Build Errors

```bash
# Clear Next.js cache
rm -rf .next

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install
```

### TypeScript Errors

```bash
# Regenerate types
npm run build
```

## Contributing

This is a scaffolding project. To extend:

1. Fork the repository
2. Create feature branch: `git checkout -b feature/new-visualization`
3. Commit changes: `git commit -am 'Add market sentiment analysis'`
4. Push to branch: `git push origin feature/new-visualization`
5. Submit pull request

## License

MIT License - See LICENSE file for details

## Resources

- [Next.js Documentation](https://nextjs.org/docs)
- [Anthropic Claude API](https://docs.anthropic.com/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [shadcn/ui Components](https://ui.shadcn.com/)
- [Recharts Documentation](https://recharts.org/)

## Support

For issues, questions, or contributions:
- Open an issue on GitHub
- Review the architecture mind map in the application
- Consult the MCP server documentation

---

Built with Claude Code and deployed on Vercel.