Installation

1. Clone the repository

git clone https://github.com/campaignos/platform.git
cd platform

2. Install PHP dependencies

composer install --no-dev --optimize-autoloader

3. Configure environment

cp .env.example .env
php artisan key:generate

Edit .env with your database, Redis, and AWS credentials. See the Configuration page for all variables.

4. Run database migrations

php artisan migrate --seed

5. Install frontend assets

npm install && npm run build

6. Start the application

# Development
php artisan serve

# Production (use Nginx + PHP-FPM or Docker)
php artisan horizon  # Start queue worker in separate terminal

The platform will be available at http://localhost:8000. Default admin credentials are in your database/seeders/AdminSeeder.php.

Offline Sync Architecture

OneTALA is designed around the assumption that field workers will operate in areas with no internet connectivity for extended periods. The sync engine handles this transparently.

How it works

Conflict resolution rules

Licence Key System

Standard and Enterprise tier deployments require a licence key issued by Seriba Technology (OneTALA). The key is validated on startup and periodically during operation. Community (self-hosted, open source) deployments do not require a key.

How it works

1. You purchase a licence and receive a key by email (e.g. CAMP-STD-2025-XXXX-XXXX)
2. Add it to your .env: CAMPAIGNOS_LICENCE_KEY=CAMP-STD-2025-XXXX-XXXX
3. On startup, the platform calls https://licence.campaignos.com/v1/validate
4. The API returns your tier, limits (beneficiary cap, user cap), and expiry date
5. The platform enforces limits in real-time. At 80% and 95% usage, admins receive alerts
6. At 100% or on expiry, the platform enters read-only mode — no data loss

Licence API reference

POST https://licence.campaignos.com/v1/validate
Content-Type: application/json

{
  "key": "CAMP-STD-2025-XXXX-XXXX",
  "domain": "kano.campaignos.com",
  "version": "1.0.4"
}

// Response
{
  "valid": true,
  "tier": "standard",
  "limits": {
    "beneficiaries": 5000000,
    "users": 7000
  },
  "usage": {
    "beneficiaries": 2341089,
    "users": 312
  },
  "expires_at": "2026-06-01",
  "renewal_url": "https://campaignos.com/pages/pricing.html"
}

API Authentication

OneTALA uses JWT (JSON Web Token) bearer token authentication. All API endpoints require a valid token except the login endpoint.

Obtain a token

POST /api/v1/auth/login
Content-Type: application/json

{
  "username": "admin@kano.gov.ng",
  "password": "your-password"
}

// Response
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 86400,
  "user": {
    "id": 1,
    "name": "Aminu Bello",
    "role": "state_coordinator",
    "geo_unit_id": 42
  }
}

Use the token

GET /api/v1/beneficiaries
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Accept: application/json

Token refresh

POST /api/v1/auth/refresh
Authorization: Bearer {current_token}

Beneficiary API

Deploying to AWS

The recommended production stack uses ECS Fargate (no servers to manage), RDS PostgreSQL Multi-AZ, ElastiCache Redis, and S3 + CloudFront. See the full deployment guide in the repository at DEPLOYMENT.md.

Quick reference — estimated costs (af-south-1)

With Reserved Instances (1yr), reduce RDS and ElastiCache costs by ~35%, bringing total to ~$420/month.