# URL Structure

## Overview

The SaaS Platform uses separate subdomains for different services to provide clean separation and better security.

## DNS Requirements

Before deploying, configure the following DNS A records (all pointing to your server's IP):

| Record Type | Name | Example | Purpose |
|-------------|------|---------|---------|
| A | `@` or root | `example.com` | Main website/Hello World |
| A | `console` | `console.example.com` | Dashboard/Admin UI |
| A | `api` | `api.example.com` | REST API endpoints |
| A | `wss` | `wss.example.com` | WebSocket server |
| A | `*` (wildcard) | `*.example.com` | User-deployed apps |

**Total: 5 DNS records required**

---

## Production URLs

Assuming your domain is `example.com`:

### Main Website
- **URL**: `https://example.com`
- **Purpose**: Public-facing hello world landing page
- **SSL**: Let's Encrypt
- **Served by**: Nginx (static files)

### Dashboard (Console)
- **URL**: `https://console.example.com`
- **Purpose**: Admin dashboard for managing the platform
- **SSL**: Let's Encrypt
- **Features**:
  - User management
  - Application deployment
  - Database editor
  - Email templates
  - SMTP settings
  - RLS policy management
  - API key management

### API Endpoint
- **URL**: `https://api.example.com`
- **Purpose**: REST API for all backend operations
- **SSL**: Let's Encrypt
- **Authentication**: JWT or API Keys
- **Endpoints**:
  - `/auth/*` - Authentication routes
  - `/users` - User management
  - `/applications` - Application CRUD
  - `/deployments` - Deployment operations
  - `/database` - Database management
  - `/rls` - RLS policies
  - `/storage` - File operations
  - `/email-queue` - Email management
  - `/email-templates` - Template CRUD
  - `/smtp-settings` - SMTP configuration
  - `/health` - Health check

**Example API Calls**:
```bash
# Health check
curl https://api.example.com/health

# Login (get JWT token)
curl -X POST https://api.example.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"password"}'

# Get users (with JWT)
curl https://api.example.com/users \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Get users (with API key)
curl https://api.example.com/v1/users \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
```

### WebSocket Server
- **URL**: `wss://wss.example.com`
- **Purpose**: Real-time bidirectional communication
- **SSL**: Let's Encrypt (WSS protocol)
- **Authentication**: JWT token required
- **Connection**:
  ```javascript
  const ws = new WebSocket('wss://wss.example.com?token=YOUR_JWT_TOKEN');
  ```

### User Applications (Wildcard)
- **URL Pattern**: `https://app-name.example.com`
- **Purpose**: Host user-deployed applications
- **SSL**: Shared Let's Encrypt wildcard certificate
- **Examples**:
  - `https://myapp.example.com`
  - `https://blog.example.com`
  - `https://shop.example.com`

---

## Development URLs

For local development (using `.env.development`):

| Service | Production | Development |
|---------|-----------|-------------|
| Main Site | `https://example.com` | `http://localhost:8888` |
| Dashboard | `https://console.example.com` | `http://localhost:8888` |
| API | `https://api.example.com` | `http://localhost:8888/api` |
| WebSocket | `wss://wss.example.com` | `ws://localhost:8888/ws` |

**Note**: In development, all services are accessed through a single port (8888) with different paths.

---

## Migration from Old URL Structure

### Old Structure (Before Update)
- Dashboard: `https://console.example.com`
- API: `https://console.example.com/api/*`
- WebSocket: `wss://console.example.com/ws`

### New Structure (Current)
- Dashboard: `https://console.example.com`
- API: `https://api.example.com/*` ✨ **Changed**
- WebSocket: `wss://wss.example.com` ✨ **Changed**

### Why Change?

1. **Cleaner URLs**: No more `/api` or `/ws` prefixes
2. **Better Security**: Separate subdomains for different services
3. **Easier CORS**: Independent CORS policies per subdomain
4. **Load Balancing**: Can scale API and WSS independently
5. **Certificate Management**: Dedicated SSL per service
6. **Professional**: Industry standard practice

---

## Frontend Configuration

### React/JavaScript

```javascript
// config.js
const API_URL = process.env.NODE_ENV === 'production'
  ? 'https://api.yourdomain.com'
  : 'http://localhost:8888/api';

const WSS_URL = process.env.NODE_ENV === 'production'
  ? 'wss://wss.yourdomain.com'
  : 'ws://localhost:8888/ws';

const CONSOLE_URL = process.env.NODE_ENV === 'production'
  ? 'https://console.yourdomain.com'
  : 'http://localhost:8888';

export { API_URL, WSS_URL, CONSOLE_URL };
```

### Environment Variables

```bash
# .env.production
VITE_API_URL=https://api.yourdomain.com
VITE_WSS_URL=wss://wss.yourdomain.com
VITE_CONSOLE_URL=https://console.yourdomain.com

# .env.development
VITE_API_URL=http://localhost:8888/api
VITE_WSS_URL=ws://localhost:8888/ws
VITE_CONSOLE_URL=http://localhost:8888
```

---

## Nginx Routing

### Simplified Routing Map

```
Port 443 (HTTPS):
├── example.com → Hello World (static files)
├── console.example.com → Dashboard (React app)
├── api.example.com → API Service (Node.js)
├── wss.example.com → WebSocket Service (Node.js)
└── *.example.com → User Apps (dynamic routing)

Port 80 (HTTP):
└── All domains → Redirect to HTTPS (301)
```

---

## Security Considerations

### CORS Configuration

Each subdomain has independent CORS:

- **console.example.com**: Strict CORS (same-origin only)
- **api.example.com**: Permissive CORS (allow all origins for API access)
- **wss.example.com**: WebSocket CORS (upgrade headers)

### SSL/TLS Certificates

- **Single Certificate**: Covers all subdomains
  - `example.com`
  - `console.example.com`
  - `api.example.com`
  - `wss.example.com`
- **Wildcard Support**: `*.example.com` (requires separate certificate or SAN)
- **Auto-renewal**: Certbot renews automatically

### Firewall Rules

```bash
# Only open ports 80 and 443
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 22/tcp  # SSH
sudo ufw enable
```

---

## Testing DNS Configuration

```bash
# Check all DNS records
dig +short A example.com
dig +short A console.example.com
dig +short A api.example.com
dig +short A wss.example.com
dig +short A test.example.com  # Test wildcard

# All should return the same IP address
```

---

## Troubleshooting

### "DNS not found" Error

**Problem**: Cannot resolve subdomain
**Solution**: Wait for DNS propagation (up to 48 hours) or check DNS configuration

```bash
# Use Google DNS for testing
dig @8.8.8.8 api.example.com
```

### SSL Certificate Error

**Problem**: Certificate doesn't cover subdomain
**Solution**: Regenerate certificate with all subdomains

```bash
sudo certbot certonly --standalone \
  -d example.com \
  -d console.example.com \
  -d api.example.com \
  -d wss.example.com
```

### WebSocket Connection Failed

**Problem**: Cannot connect to WSS
**Solution**: Check if wss.example.com resolves and has SSL

```bash
# Test WSS domain
curl -I https://wss.example.com

# Should return HTTP 200 or 400 (not 404 or connection refused)
```

---

## Summary Table

| URL | Service | Port | SSL | Authentication | Purpose |
|-----|---------|------|-----|----------------|---------|
| `https://example.com` | Nginx | 443 | ✅ | None | Landing page |
| `https://console.example.com` | Dashboard | 443 | ✅ | JWT | Admin UI |
| `https://api.example.com` | API | 443 | ✅ | JWT/API Key | REST API |
| `wss://wss.example.com` | WebSocket | 443 | ✅ | JWT | Real-time |
| `https://*.example.com` | User Apps | 443 | ✅ | Varies | Hosted apps |

---

*For deployment instructions, see [DEPLOYMENT.md](./DEPLOYMENT.md)*