citelynq.websample/README.md

# CiteLynq Web Sample

A sample ASP.NET Core web application demonstrating how to use the CiteLynq API to search for verified citations across multiple authoritative sources.

## Features

✅ ASP.NET Core 9.0 minimal API
✅ Static file hosting with wwwroot
✅ Proxy endpoints to hide API keys from client
✅ Clean, modern UI with gradient design
✅ Search across multiple data sources
✅ Display formatted citations (APA, MLA, Bluebook)
✅ Filter by source type (ArXiv, PubMed, CourtListener, etc.)
✅ Responsive design
✅ Local storage for API key persistence

## Quick Start

### 1. Get an API Key

1. Visit [https://citelynq.com/app/api-keys](https://citelynq.com/app/api-keys)
2. Create a new API key
3. Copy the key (starts with `cl_`)

### 2. Run the Application

```bash
cd /repos/CiteFlow/samples/CiteLynq.WebSample
dotnet run
```

The application will start on `http://localhost:5100`

### 3. Use the Application

1. Open your browser to `http://localhost:5100`
2. Enter your API key
3. Enter a search query (e.g., "climate change")
4. Click "Search"

## Project Structure

```
CiteLynq.WebSample/
├── Program.cs                 # ASP.NET Core minimal API
├── CiteLynq.WebSample.csproj  # Project file
├── Properties/
│   └── launchSettings.json    # Launch configuration
└── wwwroot/
    └── index.html             # Single-page application
```

## How It Works

### Backend (Program.cs)

The backend provides proxy endpoints to securely call the CiteLynq API:

1. **GET /api/search** - Proxies search requests
   - Accepts: query parameters (q, sourceType, page, pageSize)
   - Headers: X-API-Key
   - Returns: Search results from CiteLynq API

2. **GET /api/articles/{id}** - Proxies article detail requests
   - Accepts: article ID as path parameter
   - Headers: X-API-Key
   - Returns: Article details from CiteLynq API

**Why use a proxy?**
- Hides your API key from client-side code
- Prevents CORS issues
- Adds an abstraction layer for future enhancements
- Enables server-side caching if needed

### Frontend (wwwroot/index.html)

The frontend is a self-contained single-page application:

- **API Key Storage**: Saves API key in localStorage
- **Search Interface**: Query input and source filter
- **Results Display**: Shows citations with metadata
- **Responsive Design**: Works on desktop and mobile

## API Endpoints

### Search Citations

```http
GET /api/search?q=climate%20change&sourceType=ArXiv&page=1&pageSize=20
X-API-Key: cl_your-api-key-here
```

**Response:**
```json
{
  "data": {
    "results": [
      {
        "id": "arxiv-2301.12345",
        "sourceType": "ArXiv",
        "title": "Climate Change Research",
        "authors": ["Dr. Jane Smith"],
        "abstract": "...",
        "publishedDate": "2023-01-15",
        "url": "https://arxiv.org/abs/2301.12345",
        "citations": {
          "apa": "Smith, J. (2023)...",
          "mla": "Smith, Jane...",
          "chicago": "..."
        }
      }
    ],
    "totalCount": 145
  }
}
```

### Get Article Details

```http
GET /api/articles/arxiv-2301.12345
X-API-Key: cl_your-api-key-here
```

## Configuration

### Change API Base URL

Edit `Program.cs` line 24 to point to a different API:

```csharp
const string API_BASE_URL = "https://citelynq.com/api";
// Or for local development:
// const string API_BASE_URL = "http://localhost:5000/api";
```

### Change Port

Edit `Properties/launchSettings.json`:

```json
{
  "profiles": {
    "http": {
      "applicationUrl": "http://localhost:5100"
    }
  }
}
```

## Development

### Prerequisites

- .NET 9.0 SDK
- Visual Studio 2022 / VS Code / Rider

### Build

```bash
dotnet build
```

### Run

```bash
dotnet run
```

### Publish

```bash
dotnet publish -c Release -o ./publish
```

## Customization

### Add More Endpoints

Add new proxy endpoints in `Program.cs`:

```csharp
app.MapGet("/api/sources", async (HttpContext context, IHttpClientFactory httpClientFactory) =>
{
    var apiKey = context.Request.Headers["X-API-Key"].FirstOrDefault();
    var httpClient = httpClientFactory.CreateClient();
    var httpRequest = new HttpRequestMessage(HttpMethod.Get, $"{API_BASE_URL}/sources");
    httpRequest.Headers.Add("X-API-Key", apiKey);
    var response = await httpClient.SendAsync(httpRequest);
    return Results.Content(await response.Content.ReadAsStringAsync(), "application/json");
});
```

### Customize UI

Edit `wwwroot/index.html`:

```css
/* Change color scheme */
body {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}
```

### Add Pagination

Add pagination controls in the HTML:

```javascript
function displayResults(data) {
    // ... existing code ...

    if (data.totalPages > 1) {
        html += `<div class="pagination">
            <button onclick="loadPage(${data.currentPage - 1})">Previous</button>
            <span>Page ${data.currentPage} of ${data.totalPages}</span>
            <button onclick="loadPage(${data.currentPage + 1})">Next</button>
        </div>`;
    }
}
```

## Security Notes

⚠️ **Important:**

1. **API Key Protection**: The proxy pattern keeps API keys server-side
2. **CORS**: Configured for development (allow all origins). Restrict in production.
3. **Input Validation**: Always validate user input
4. **HTTPS**: Use HTTPS in production environments

## Troubleshooting

### Port Already in Use

Change the port in `Properties/launchSettings.json`

### CORS Errors

The application includes CORS middleware for development. For production, configure specific origins:

```csharp
builder.Services.AddCors(options =>
{
    options.AddDefaultPolicy(policy =>
    {
        policy.WithOrigins("https://yourdomain.com")
              .AllowAnyMethod()
              .AllowAnyHeader();
    });
});
```

### API Key Not Working

1. Verify the key starts with `cl_`
2. Check the key is active in your account
3. Ensure the key has available credits

## Learn More

- **CiteLynq API Docs**: [https://citelynq.com/docs](https://citelynq.com/docs)
- **Get API Key**: [https://citelynq.com/app/api-keys](https://citelynq.com/app/api-keys)
- **ASP.NET Core**: [https://docs.microsoft.com/aspnet/core](https://docs.microsoft.com/aspnet/core)

## License

This sample is provided as-is for demonstration purposes.