System Administration Documentation

Welcome to the SYNDI system administration documentation. This guide serves system administrators, DevOps engineers, and developers responsible for deploying, configuring, and maintaining CLAIRE, PAUL, and SAM systems.

🎯 Quick Navigation by Role

👨‍💻 For New Developers

Start here if you’re setting up a development environment for the first time:

  1. Local Development Setup - Set up your development environment

  2. Local Development Workflow - Daily development tasks

  3. Testing Guide - How to test your changes

Quick Command:

# Set up and start local development
make setup-local ENV=dev ORG=myorg
make start-dev ENV=dev ORG=myorg

🚀 For System Administrators

Start here if you’re deploying or managing production systems:

  1. First Deployment Guide - Deploy SYNDI for the first time

  2. Configuration System - Understand how configuration works

  3. User Management - Manage users and permissions

  4. Monitoring & Troubleshooting - Keep systems healthy

Quick Command:

# Deploy new organization to production
ENABLE_AUTH=true CREATE_BUCKETS=true \
  ADMIN_USERNAME=admin@myorg.com ADMIN_PASSWORD=SecurePass2025! \
  ORG=myorg ENV=prod make rs-deploy

⚙️ For DevOps Engineers

Start here if you’re managing infrastructure and deployments:

  1. Deployment Architecture - How deployment works

  2. Makefile Deployment Guide - Primary deployment method

  3. Multi-Organization Setup - Supporting multiple organizations

  4. CloudWatch Monitoring - Monitor production systems

Quick Command:

# Quick Lambda code update
ORG=myorg ENV=stage make rs-deploy-function

# Full stack deployment
ORG=myorg ENV=stage ENABLE_AUTH=true make rs-deploy

📚 Complete Documentation Index

Getting Started

System Architecture

Deployment

Configuration

Development

Authentication & RBAC

Monitoring & Maintenance

Reference

🏗️ Infrastructure Overview

SYNDI supports multiple deployment architectures:

Local Development

  • Backend: FastAPI server with hot reload (localhost:8000)

  • Frontend: Vite development server (localhost:3000)

  • Storage: Local filesystem simulating S3 (.local/s3/)

  • Authentication: Mock authentication for development

  • Command: make start-dev ENV=dev ORG=myorg

AWS Cloud (Production)

  • Backend: Lambda function with API Gateway

  • Frontend: S3 + CloudFront CDN

  • Storage: S3 buckets with encryption and versioning

  • Authentication: AWS Cognito with role-based access control

  • Command: ORG=myorg ENV=prod make rs-deploy

Multi-Organization Support

  • Isolation: Separate Cognito User Pools per organization

  • Resources: Separate Lambda functions and S3 buckets per organization

  • Data: Complete data and user isolation between organizations

  • Scaling: Independent scaling and monitoring per organization

🔧 Key Concepts

Configuration Hierarchy

SYNDI uses a three-tier configuration system:

  1. CloudFormation Outputs → Lambda environment variables (infrastructure values)

  2. Base JSON configs → Application behavior settings

  3. Org-specific overrides → Organization-specific customizations

Read more: Configuration System Architecture

Deployment Parameters

All deployments use four key parameters:

  • ENV: Environment (dev, test, stage, prod)

  • ORG: Organization identifier (required, no default)

  • ENABLE_AUTH: Enable Cognito authentication (true/false)

  • CREATE_BUCKETS: Create S3 buckets (true for first deploy, false for updates)

Read more: Makefile Deployment Guide

Resource Naming Convention

All AWS resources follow this pattern:

  • Lambda: rawscribe-{env}-{org}-backend

  • API Gateway: rawscribe-{env}-{org}-api

  • S3 Buckets: rawscribe-{service}-{env}-{org}-{accountid}

  • Cognito: rawscribe-{env}-{org}-userpool

Read more: AWS Resources Reference

📋 Common Tasks Quick Reference

Initial Setup

# First-time organization deployment
ENABLE_AUTH=true CREATE_BUCKETS=true \
  ADMIN_USERNAME=admin@myorg.com ADMIN_PASSWORD=SecurePass! \
  ORG=myorg ENV=stage make rs-deploy

# Sync configuration files
make sync-configs ENV=stage ORG=myorg

Daily Development

# Start local development servers
make setup-local ENV=dev ORG=myorg
make start-dev ENV=dev ORG=myorg

# Run tests
make test-all ORG=myorg

Deployment Updates

# Quick code-only update (30 seconds)
ORG=myorg ENV=stage make rs-deploy-function

# Configuration changes (2 minutes)
ORG=myorg ENV=stage make rs-deploy-only

# Full rebuild (5 minutes)
ORG=myorg ENV=stage make rs-deploy

Monitoring

# Check deployment status
ORG=myorg ENV=stage make check-rs

# View Lambda logs
ORG=myorg ENV=stage make rs-watch-log

# Test authentication
ORG=myorg ENV=stage make test-jwt-aws

⚠️ Important Security Notes

  1. No Default Organization: ORG parameter is required for all commands (prevents accidental deployments)

  2. Environment Isolation: Each ENV/ORG combination is completely isolated

  3. Credentials: Never hardcode credentials; use environment variables or AWS Secrets Manager

  4. Config Files: infra/.config/ directory is NOT in version control

  5. Production Deployments: Always use ENABLE_AUTH=true for production

🆘 Getting Help