Content Standards API

A high-performance API service for analyzing content against Atlassian content standards, optimized for Vercel deployment.

Features

• Content Analysis: Comprehensive analysis against Atlassian voice & tone, inclusive language, and plain language standards
• OpenAI Integration: Powered by GPT-4o for intelligent content analysis
• Vercel Optimized: Designed for serverless deployment with automatic scaling
• TypeScript: Fully typed with comprehensive error handling
• Request Validation: Robust input validation using Zod schemas
• Logging System: Built-in analysis logging and monitoring

API Endpoints

Core Endpoints

• POST /api/v1/analyze - Analyze content for standards violations
• GET /api/v1/status - Get API status and configuration
• GET /api/v1/logs - Get recent analysis logs
• GET /health - Health check endpoint

Request Format

{
  "content_groups": [
    {
      "group_id": "unique_identifier",
      "file_path": "path/to/file.tsx",
      "content_items": [
        {
          "text": "Content to analyze",
          "element_type": "ui_text",
          "line_number": 42,
          "element_context": "button label"
        }
      ]
    }
  ]
}

Response Format

{
  "analysis_results": [...],
  "summary": {
    "total_violations": 5,
    "severity_breakdown": {
      "error": 2,
      "warning": 3,
      "info": 0
    },
    "most_common_issues": ["active_voice", "plain_language"]
  },
  "metadata": {
    "response_time_ms": 2341,
    "model_used": "gpt-4o",
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}

Local Development

1. Install dependencies:

   npm install

2. Set environment variables:

   export OPENAI_API_KEY="your-openai-api-key"

3. Build and run:

   npm run build
   npm start

4. Development mode:

   npm run dev

Vercel Deployment

1. Push to GitHub and connect to Vercel

2. Set environment variables in Vercel dashboard:

   • OPENAI_API_KEY: Your OpenAI API key

3. Deploy: Automatic deployment on git push

Environment Variables

• OPENAI_API_KEY - Required: OpenAI API key for GPT-4o access
• PORT - Optional: Server port (default: 3000, Vercel handles this)
• NODE_ENV - Optional: Environment mode (development/production)

Performance

• Timeout: 300 seconds maximum for large analysis requests
• Memory: Optimized for serverless constraints
• Scaling: Automatic scaling via Vercel's serverless functions

Standards Analyzed

1. Atlassian Voice & Tone

   • Brand personality consistency
   • User context-appropriate tone
   • Clear, helpful communication

2. Inclusive Language

   • Non-inclusive term detection
   • Pronoun usage guidelines
   • Person-first language

3. Plain Language

   • Reading level optimization
   • Complex term simplification
   • Positive language framing

4. Accessibility

   • Alt text requirements
   • Descriptive link text
   • Clear language guidelines

Error Handling

• Comprehensive request validation
• OpenAI API error management
• Rate limit handling with appropriate responses
• Graceful degradation for service issues

Monitoring

• Built-in request logging
• Memory usage monitoring for large requests
• Performance metrics tracking
• Health check endpoints for uptime monitoring