Skip to main content
Version: 1.0

Synkronus Server Reference

Complete technical reference for the Synkronus server component.

Overview

Synkronus is a robust synchronization API server built with Go. It provides RESTful endpoints for data synchronization, app bundle management, attachment handling, user management, and form specifications. The server uses PostgreSQL for data storage and JWT for authentication.

Architecture

Technology Stack

  • Language: Go 1.22+
  • Database: PostgreSQL 12+
  • Authentication: JWT (JSON Web Tokens)
  • API: RESTful HTTP API
  • Documentation: OpenAPI 3.0 specification

Project Structure

synkronus/
├── cmd/synkronus/         # Application entry point
├── internal/              # Private application code
│   ├── api/               # API definition and OpenAPI integration
│   ├── handlers/          # HTTP request handlers
│   ├── models/            # Domain models
│   ├── repository/        # Data access layer
│   └── services/          # Business logic
└── pkg/                   # Public libraries
    ├── auth/              # Authentication utilities
    ├── database/          # Database connection and migrations
    ├── logger/            # Structured logging
    ├── middleware/        # HTTP middleware
    └── openapi/           # OpenAPI generated code

Core Features

Data Synchronization

  • Bidirectional Sync: Push and pull operations
  • Incremental Updates: Only sync changed data
  • Conflict Resolution: Version-based conflict handling
  • Client Tracking: Track client sync state

App Bundle Management

  • Version Control: Multiple bundle versions
  • Activation: Switch active bundle version
  • File Serving: Serve bundle files to clients
  • Manifest Generation: Automatic manifest creation

Attachment Handling

  • Binary Storage: Store attachments separately from observations
  • Immutable Attachments: Once uploaded, cannot be modified
  • Efficient Transfer: Optimized for large files
  • Manifest System: Track attachment changes

User Management

  • JWT Authentication: Secure token-based auth
  • Role-Based Access: read-only, read-write, admin roles
  • User CRUD: Create, read, update, delete users
  • Password Management: Secure password handling

Form Specifications

  • Versioned Forms: Multiple versions per form type
  • Schema Storage: Store JSON schemas
  • UI Schema Support: Store UI layout definitions
  • Version Negotiation: Client requests specific versions

API Endpoints

Authentication

POST /auth/login

Authenticate user and receive JWT token.

Request:

{
  "username": "user",
  "password": "password"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 3600
}

POST /auth/refresh

Refresh expired JWT token.

Request:

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}

Synchronization

POST /sync/pull

Pull changes from server.

Request:

{
  "clientId": "client-123",
  "currentVersion": 100,
  "schemaTypes": ["survey", "visit"]
}

Response:

{
  "changes": {
    "observations": [...]
  },
  "timestamp": 150
}

POST /sync/push

Push changes to server.

Request:

{
  "clientId": "client-123",
  "changes": {
    "observations": [...]
  }
}

Response:

{
  "timestamp": 150,
  "conflicts": []
}

App Bundles

GET /app-bundle/manifest

Get current app bundle manifest.

Response:

{
  "version": "20250114-123456",
  "files": [...],
  "hash": "abc123..."
}

GET /app-bundle/download/{path}

Download app bundle file.

Path Parameters:

  • path: File path within bundle

POST /app-bundle/push

Upload new app bundle (admin only).

Request: Multipart form with bundle file

Response:

{
  "version": "20250114-123456",
  "manifest": {...}
}

GET /app-bundle/versions

List all app bundle versions.

POST /app-bundle/switch

Switch active bundle version (admin only).

Attachments

GET /attachments/manifest

Get attachment manifest.

Query Parameters:

  • since: Timestamp to get changes since

GET /attachments/{id}

Download attachment file.

POST /attachments

Upload attachment (multipart form).

Form Specifications

GET /formspecs/{formType}/{version}

Get form specification.

Path Parameters:

  • formType: Form type identifier
  • version: Form version

POST /formspecs

Create form specification (admin only).

Users

GET /users

List all users (admin only).

POST /users/create

Create new user (admin only).

GET /users/{username}

Get user details.

PUT /users/{username}

Update user (admin only).

DELETE /users/{username}

Delete user (admin only).

Data Export

GET /data/export

Export observations as Parquet ZIP.

Query Parameters:

  • format: Export format (parquet, json, csv)

Configuration

Environment Variables

VariableDescriptionDefaultRequired
PORTHTTP server port8080No
DB_CONNECTIONPostgreSQL connection string-Yes
JWT_SECRETSecret for JWT signing-Yes
LOG_LEVELLogging level (debug, info, warn, error)infoNo
APP_BUNDLE_PATHDirectory for app bundles./data/app-bundlesNo
MAX_VERSIONS_KEPTMaximum bundle versions to keep5No
ADMIN_USERNAMEInitial admin usernameadminNo
ADMIN_PASSWORDInitial admin passwordadminNo

Example Configuration

PORT=8080
DB_CONNECTION=postgres://user:password@localhost:5432/synkronus?sslmode=disable
JWT_SECRET=your-secret-key-change-this-in-production
LOG_LEVEL=info
APP_BUNDLE_PATH=./data/app-bundles
MAX_VERSIONS_KEPT=5
ADMIN_USERNAME=admin
ADMIN_PASSWORD=admin

Database Schema

Observations Table

ColumnTypeDescription
idUUIDPrimary key
form_typeVARCHARForm type identifier
dataJSONBObservation data
created_atTIMESTAMPCreation timestamp
updated_atTIMESTAMPLast update timestamp
deletedBOOLEANSoft delete flag
versionINTEGERVersion number (auto-increment)

Users Table

ColumnTypeDescription
idUUIDPrimary key
usernameVARCHARUnique username
password_hashVARCHARHashed password
roleVARCHARUser role (read-only, read-write, admin)
created_atTIMESTAMPCreation timestamp

App Bundle Versions Table

ColumnTypeDescription
versionVARCHARVersion identifier
is_activeBOOLEANActive version flag
created_atTIMESTAMPCreation timestamp

Synchronization Protocol

Two-Phase Sync

Phase 1: Observation Sync

  1. Client requests changes via /sync/pull
  2. Server returns observations changed since client's version
  3. Client applies changes locally
  4. Client pushes local changes via /sync/push
  5. Server applies changes and returns new version

Phase 2: Attachment Sync

  1. Client requests attachment manifest
  2. Server returns list of attachments to download
  3. Client downloads missing attachments
  4. Client uploads pending attachments
  5. Server confirms receipt

Conflict Resolution

Conflicts are detected when:

  • Same observation modified on multiple clients
  • Observation deleted on one client, modified on another

Resolution strategy:

  • Last Write Wins: Most recent change wins
  • Version Tracking: Version numbers prevent conflicts
  • Client Responsibility: Clients handle conflict resolution

Security

Authentication

  • JWT Tokens: Secure token-based authentication
  • Token Expiration: Tokens expire after configured time
  • Refresh Tokens: Long-lived refresh tokens
  • Password Hashing: bcrypt password hashing

Authorization

  • Role-Based Access: Three roles (read-only, read-write, admin)
  • Endpoint Protection: Middleware protects admin endpoints
  • Token Validation: All requests validate JWT tokens

Data Protection

  • HTTPS: Recommended for production
  • Input Validation: All inputs validated
  • SQL Injection Prevention: Parameterized queries
  • XSS Protection: Input sanitization

Deployment

Docker Deployment

See Deployment Guide for complete deployment instructions.

Quick Start

docker compose up -d

Production Setup

  1. Configure environment variables
  2. Set up PostgreSQL database
  3. Configure reverse proxy (Nginx)
  4. Set up SSL/TLS certificates
  5. Configure monitoring and logging

Monitoring

Health Check

curl http://localhost:8080/health

Returns OK if server is healthy.

Logging

Structured logging with levels:

  • Debug: Detailed debugging information
  • Info: General informational messages
  • Warn: Warning messages
  • Error: Error messages

Metrics

Key metrics to monitor:

  • Request rate
  • Response times
  • Error rates
  • Database connection pool
  • Active sync operations

Performance

Optimization Strategies

  • Connection Pooling: PostgreSQL connection pool
  • Query Optimization: Indexed database queries
  • Caching: Cache app bundle manifests
  • Compression: Compress responses when possible

Scaling

  • Horizontal Scaling: Multiple server instances
  • Load Balancing: Distribute requests across instances
  • Database Replication: Read replicas for database
  • CDN: Serve static files via CDN

Troubleshooting

Common Issues

Database Connection Errors:

  • Verify PostgreSQL is running
  • Check connection string format
  • Verify database exists
  • Check user permissions

Authentication Failures:

  • Verify JWT_SECRET is set
  • Check token expiration
  • Verify user credentials

Sync Failures:

  • Check database connectivity
  • Verify client version tracking
  • Review server logs

API Versioning

The API supports versioning via the x-api-version header:

x-api-version: 1.0.0

Version negotiation allows clients to request specific API versions.