Development workflow, deployment, and architecture guide for the Vikings Event Management API - a Node.js Express backend serving as an OAuth proxy for Online Scout Manager (OSM) API integration with auto-deployment to Railway.
A comprehensive guide for working with the Vikings Event Management API codebase - a Node.js Express backend that serves as an OAuth proxy for Online Scout Manager (OSM) API integration.
This skill provides guidance for development, testing, deployment, and troubleshooting of the Vikings Event Management API. The backend uses **auto-deployment** where code merged to `main` automatically deploys to production on Railway.
**Core Components:**
**Key Features:**
```bash
npm start # Production server
npm run dev # Development with auto-restart (nodemon)
npm run build # No build step (echo message)
```
```bash
npm run lint # ESLint checks
```
```bash
npm test # Run all tests
npm run test:watch # Watch mode for development
npm run test:coverage # With coverage report
npm run test:ci # CI mode (no watch, with coverage)
```
**Test Coverage:** 53 tests covering all endpoints, rate limiting, CORS, OAuth flow, frontend URL detection, health checks, documentation, error handling, and security edge cases.
**Step 1: Feature Development**
```bash
git checkout -b feature/my-feature
npm run lint && npm test && npm run build # Verify before PR
```
**Step 2: Version Management (BEFORE merge)**
```bash
npm run version:patch # Updates package.json only (--no-git-tag-version)
git add package.json package-lock.json
git commit -m "chore: bump version to v1.x.x for production deployment"
```
**Step 3: PR Review & Merge**
**Step 4: Post-Merge Release Finalization**
```bash
git checkout main && git pull origin main # Sync with merged changes
git tag -a v1.x.x -m "Release v1.x.x: Description of changes"
git push origin v1.x.x
npm run release:finalize # Finalize Sentry release
```
**When fixing critical production errors:**
**Step 1: Create Hotfix Branch**
```bash
git checkout -b feature/hotfix-critical-issue
```
**Step 2: Implement Fix**
**Step 3: Update Version BEFORE Merge (Critical!)**
```bash
npm run version:patch
git add package.json package-lock.json
git commit -m "chore: bump to v1.x.x for critical production fix"
```
**Step 4: PR with Detailed Context**
**Step 5: Post-Merge Release Tag**
```bash
git checkout main && git pull origin main
git tag -a v1.x.x -m "Release v1.x.x: Critical fixes for [issue description]"
git push origin v1.x.x
npm run release:finalize
```
**Development Releases:**
```bash
./scripts/release.sh patch # Automated version bump + Sentry integration
```
**Version Management:**
```bash
npm run version:patch # Bump patch version (no git operations)
npm run version:minor # Bump minor version (no git operations)
npm run version:major # Bump major version (no git operations)
```
**Manual Release Process (Fallback):**
```bash
npm run release:patch # Test + bump patch version
npm run release:minor # Test + bump minor version
npm run release:major # Test + bump major version
```
**Sentry Integration:**
```bash
npm run release:create # Create new Sentry release
npm run release:finalize # Finalize release for deployment tracking
npm run release:deploy # Mark deployment with commit info
```
1. `frontend_url` query parameter (highest priority)
2. Embedded URL in state: `state=prod&frontend_url=https://pr-123-vikings-eventmgmt.onrender.com`
3. Referer header detection for `.onrender.com` domains
4. Legacy state-based detection (`state=dev` → `https://localhost:3000`)
5. Default: `https://vikings-eventmgmt.onrender.com`
**Critical Requirement:** The `redirect_uri` must match exactly between:
1. Initial OAuth authorization request (frontend)
2. Token exchange request (backend)
**Common Issues:**
**Debugging Steps:**
1. Check `/oauth/debug` endpoint to verify `backendUrl` and `authUrl`
2. Verify `VITE_API_URL` (frontend) matches `BACKEND_URL` (backend)
3. Test OAuth flow locally to isolate environment vs code issues
4. Compare browser network requests for exact redirect URI mismatches
**Example Valid Configuration:**
```env
BACKEND_URL=https://vikingeventmgmtapi-production.up.railway.app
VITE_API_URL=https://vikingeventmgmtapi-production.up.railway.app
```
```env
OAUTH_CLIENT_ID=your_osm_client_id
OAUTH_CLIENT_SECRET=your_osm_client_secret
NODE_ENV=development|production|test
PORT=3000
SENTRY_DSN=optional_sentry_dsn
BACKEND_URL=backend_base_url
```
**Import Pattern:**
```javascript
const Sentry = require('../config/sentry');
const { logger } = Sentry;
```
**Logging Patterns:**
**Example:**
```javascript
logger.info('Processing request', { endpoint, sessionId, params });
logger.error('Request failed', { endpoint, sessionId, error: err.message });
```
**Authentication:**
**OSM Proxy (require Authorization header):**
**Utility:**
**Benefits:**
**Key Utilities:**
1. Monitor Sentry for error patterns and rate limit issues
2. Check Railway deployment logs for startup errors
3. Verify API endpoints are responding correctly
4. Monitor OAuth callback functionality
5. Review rate limit metrics and OSM API integration
Use this skill when:
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/vikings-event-management-api-development-guide/raw