Developer Guide¶

Welcome to the Studio Platform Developer Guide! This comprehensive guide covers everything developers need to know about the Studio Platform, from API integration to custom development and contribution guidelines.

🎯 Who This Guide Is For¶

This guide is designed for:

API Developers - Integrating with Studio Platform APIs
Frontend Developers - Building custom frontend applications
Backend Developers - Extending backend functionality
DevOps Engineers - Deploying and managing the platform
Security Engineers - Implementing security integrations
Compliance Engineers - Building compliance solutions

📚 Developer Guide Structure¶

API Development¶

API Reference - Complete API documentation
Authentication - API authentication and authorization
Rate Limiting - API rate limiting and quotas
Error Handling - API error handling and responses
Webhooks - Webhook configuration and usage

Development¶

Architecture - System architecture and design
Database Schema - Database structure and relationships
Development Setup - Local development environment
Testing - Testing frameworks and procedures
Deployment - Deployment strategies and procedures

Integrations¶

Third-Party Integrations - Integration with external services
Custom Extensions - Building custom extensions
Plugins - Plugin development and management
Themes - Custom theme development
Workflows - Custom workflow development

Contributing¶

Contributing Guidelines - How to contribute to the platform
Code Style - Coding standards and conventions
Pull Requests - Pull request guidelines
Issue Reporting - Bug reporting and feature requests
Documentation - Documentation guidelines

🚀 Quick Start for Developers¶

API Access Setup¶

Step 1: Get API Credentials¶

Register for API Access
Navigate to developer portal
Register your application
Obtain API credentials
Configure Authentication
Set up OAuth 2.0 flow
Configure API keys
Test authentication
Make First API Call
Use API documentation
Test with sample code
Verify response

Step 2: Development Environment¶

Development Setup:

# Clone the repository
git clone https://github.com/OmerRastgar/studio.git
cd studio

# Install dependencies
npm install

# Start development server
npm run dev

# Run tests
npm test

Environment Configuration:

# Copy environment template
cp .env.example .env

# Configure environment variables
nano .env

# Start services
docker-compose up -d

Development Tools¶

Required Tools¶

Development Tools: - Node.js - JavaScript runtime (v18+) - npm - Package manager (v8+) - Docker - Container platform (v20+) - Docker Compose - Multi-container orchestration - Git - Version control system - VS Code - Recommended IDE

Optional Tools: - Postman - API testing - DBeaver - Database management - Redis Desktop Manager - Redis management - MongoDB Compass - MongoDB management

IDE Configuration¶

VS Code Extensions:

{
  "recommendations": [
    "ms-vscode.vscode-json",
    "bradlc.vscode-tailwindcss",
    "esbenp.prettier-vscode",
    "dbaeumer.vscode-eslint",
    "ms-vscode.vscode-typescript-next",
    "ms-vscode-remote.remote-containers"
  ]
}

VS Code Settings:

{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.preferences.importModuleSpecifier": "relative"
}

🔧 Development Overview¶

Platform Architecture¶

Microservices Architecture¶

graph TD
    A[Frontend] --> B[API Gateway]
    B --> C[Backend Service]
    B --> D[AI Service]
    B --> E[Document RAG Service]

    C --> F[PostgreSQL]
    C --> G[Neo4j]
    C --> H[Redis]

    D --> I[Vector Store]
    D --> J[AI Models]

    E --> K[Document Storage]
    E --> L[Processing Queue]

    M[Fleet Service] --> F
    N[Prowler Service] --> F
    O[Monitoring] --> P[Prometheus]
    O --> Q[Grafana]

Technology Stack¶

Frontend:

Framework - Next.js 13+
Language - TypeScript
Styling - Tailwind CSS
UI Components - Radix UI
State Management - React Query
Forms - React Hook Form

Backend:

Runtime - Node.js 18+
Language - TypeScript
Framework - Express.js
Database - PostgreSQL, Neo4j, Redis
Authentication - Ory Kratos
Authorization - Open Policy Agent

Infrastructure:

Containerization - Docker
Orchestration - Docker Compose
API Gateway - Kong
Monitoring - Prometheus, Grafana
Logging - Loki, Fluent Bit

API Architecture¶

RESTful API Design¶

API Principles:

RESTful Design - Follow REST principles
Resource-Based - Resource-oriented URLs
HTTP Methods - Proper use of HTTP methods
Status Codes - Appropriate HTTP status codes
Versioning - API versioning strategy

API Endpoints:

📊 API Endpoints Structure

   Authentication:
   POST /api/v1/auth/login
   POST /api/v1/auth/logout
   POST /api/v1/auth/refresh
   GET  /api/v1/auth/profile

   Users:
   GET  /api/v1/users
   GET  /api/v1/users/:id
   POST /api/v1/users
   PUT  /api/v1/users/:id
   DELETE /api/v1/users/:id

   Projects:
   GET  /api/v1/projects
   GET  /api/v1/projects/:id
   POST /api/v1/projects
   PUT  /api/v1/projects/:id
   DELETE /api/v1/projects/:id

   Evidence:
   GET  /api/v1/evidence
   GET  /api/v1/evidence/:id
   POST /api/v1/evidence
   PUT  /api/v1/evidence/:id
   DELETE /api/v1/evidence/:id

   Compliance:
   GET  /api/v1/compliance/score
   GET  /api/v1/compliance/frameworks
   GET  /api/v1/compliance/controls
   GET  /api/v1/compliance/gaps

   AI Assistant:
   POST /api/v1/ai/chat
   POST /api/v1/ai/analyze
   POST /api/v1/ai/generate
   GET  /api/v1/ai/suggestions

🔐 Authentication & Authorization¶

API Authentication¶

OAuth 2.0 Flow¶

OAuth 2.0 Configuration:

🔐 OAuth 2.0 Configuration

   Grant Types:
   🔑 Authorization Code: Web applications
   🔑 Client Credentials: Service-to-service
   🔑 Refresh Token: Token refresh
   🔑 Device Code: Device authorization

   Token Configuration:
   🔑 Access Token: 1 hour expiration
   🔑 Refresh Token: 30 days expiration
   🔑 Token Type: Bearer
   🔑 Token Format: JWT

   Scopes:
   🔑 read: Read access
   🔑 write: Write access
   🔑 admin: Admin access
   🔑 audit: Audit access
   🔑 webhook: Webhook access

API Key Authentication¶

API Key Configuration:

🔑 API Key Configuration

   API Key Types:
   🔑 Production: Production access
   🔑 Development: Development access
   🔑 Testing: Testing access
   🔑 Custom: Custom access

   Key Management:
   🔑 Generation: Automated
   🔑 Rotation: Quarterly
   🔑 Revocation: Immediate
   🔑 Expiration: Configurable

   Access Control:
   🔑 Rate Limiting: Per key
   🔑 IP Restrictions: Configurable
   🔑 Time Restrictions: Configurable
   🔑 Resource Restrictions: Configurable

📊 API Reference¶

API Documentation¶

OpenAPI Specification¶

OpenAPI Configuration:

openapi: 3.0.0
info:
  title: Studio Platform API
  description: Comprehensive compliance management platform API
  version: 1.0.0
  contact:
    name: API Support
    email: [email protected]
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.studio.com/v1
    description: Production server
  - url: https://staging-api.studio.com/v1
    description: Staging server
  - url: http://localhost:4000/v1
    description: Development server

security:
  - OAuth2: []
  - ApiKeyAuth: []

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.studio.com/oauth/authorize
          tokenUrl: https://auth.studio.com/oauth/token
          scopes:
            read: Read access
            write: Write access
            admin: Admin access
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

API Response Format¶

Standard Response Format:

{
  "success": true,
  "data": {
    "id": "123",
    "name": "Example Resource",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  },
  "message": "Resource retrieved successfully",
  "timestamp": "2024-01-01T00:00:00Z",
  "request_id": "req_123456789"
}

Error Response Format:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "field": "email",
      "error": "Invalid email format"
    }
  },
  "timestamp": "2024-01-01T00:00:00Z",
  "request_id": "req_123456789"
}

🧪 Testing¶

Testing Framework¶

Testing Stack¶

Testing Tools: - Unit Testing - Jest - Integration Testing - Supertest - E2E Testing - Playwright - API Testing - Postman/Newman - Performance Testing - Artillery

Test Configuration:

id=__codelineno-10-1 name=__codelineno-10-1 href=#__codelineno-10-1>{ "scripts": { "test": "jest", "test:watch": "jest --watch", "test:coverage": "jest --coverage", "test:integration": "jest --config jest.integration.config.js", "test:e2e": "playwright test", "test:api": "newman run tests/api/postman_collection.json" }, "jest": { "testEnvironment": "node", "coverageDirectory": "coverage", "coverageReporters": ["text", "lcov", "html"], "collectCoverageFrom": [ "src/**/*.ts", "!src/**/*.d.ts", "!src/**/*.test.ts" ] } class=p>}

Test Structure¶

Test Organization:

🧪 Test Structure

   Unit Tests:
   📁 tests/unit/
     📁 services/
     📁 controllers/
     📁 utils/
     📁 models/

   Integration Tests:
   📁 tests/integration/
     📁 api/
     📁 database/
     📁 auth/

   E2E Tests:
   📁 tests/e2e/
     📁 pages/
     📁 workflows/
     📁 scenarios/

   API Tests:
   📁 tests/api/
     📁 endpoints/
     📁 authentication/
     📁 validation/

🚀 Deployment¶

Deployment Strategies¶

Container Deployment¶

Docker Configuration:

# Backend Dockerfile
FROM node:18-alpine AS builder

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

FROM node:18-alpine AS runtime

RUN addgroup -g 1001 -S nodejs
RUN adduser -S nodejs -u 1001

WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist

USER nodejs

EXPOSE 4000

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:4000/api/health || exit 1

CMD ["npm", "start"]

Docker Compose:

version: '3.8'

services:
  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile
    ports:
      - "4000:4000"
    environment:
      - NODE_ENV=production
      - DATABASE_URL=postgresql://user:password@postgres:5432/studio
    depends_on:
      - postgres
      - redis
      - neo4j

  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile
      target: production
    ports:
      - "3000:3000"
    environment:
      - NEXT_PUBLIC_API_URL=http://localhost:4000
    depends_on:
      - backend

CI/CD Pipeline¶

GitHub Actions Configuration:

name: CI/CD Pipeline

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm ci
      - run: npm run test:coverage
      - uses: codecov/codecov-action@v3

  build:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: docker/setup-buildx-action@v2
      - uses: docker/build-push-action@v4
        with:
          context: .
          push: true
          tags: your-registry/studio:latest

🤝 Contributing¶

Contribution Guidelines¶

Development Workflow¶

Contribution Process:

graph TD
    A[Fork Repository] --> B[Create Feature Branch]
    B --> C[Make Changes]
    C --> D[Write Tests]
    D --> E[Run Tests]
    E --> F[Submit Pull Request]
    F --> G[Code Review]
    G --> H[Merge Changes]
    H --> I[Release]

Branching Strategy: - main - Production-ready code - develop - Development integration - feature/* - Feature development - bugfix/* - Bug fixes - hotfix/* - Production hotfixes

Code Standards¶

Coding Standards: - TypeScript - Use TypeScript for all new code - ESLint - Follow ESLint rules - Prettier - Use Prettier for formatting - Conventional Commits - Use conventional commit messages - Tests - Write tests for all new features

Code Review Guidelines: - Review Checklist - Use review checklist - Approval Process - Require approval before merge - Automated Checks - All automated checks must pass - Documentation - Update documentation as needed

✅ Developer Success Tips¶

Best Practices¶

Development Best Practices¶

Code Quality - Maintain high code quality standards
Testing - Write comprehensive tests
Documentation - Keep documentation up to date
Performance - Optimize for performance
Security - Follow security best practices

API Development Best Practices¶

RESTful Design - Follow REST principles
Error Handling - Handle errors gracefully
Rate Limiting - Respect rate limits
Authentication - Use proper authentication
Versioning - Use API versioning

Common Development Mistakes¶

❌ Avoid These Mistakes: - Not writing tests for new features - Not following coding standards - Not updating documentation - Not handling errors properly - Not following security best practices

✅ Follow These Best Practices: - Write comprehensive tests for all features - Follow coding standards and conventions - Keep documentation up to date - Handle errors gracefully and appropriately - Follow security best practices

!!! tip Start Small Begin with simple API integrations and gradually build more complex features as you become familiar with the platform.

!!! note Documentation First Write documentation before or alongside code to ensure comprehensive and accurate documentation.

!!! question Need Help? Check our API Reference for detailed API documentation, or contact our developer support team for assistance.