Evolvus Orbit Server

Backend API for Evolvus Orbit, implemented with FastAPI + MongoDB.

This service powers all Orbit workspaces used by the portal:

• Auth/session and JWT issuance
• Dashboard aggregation
• Travel workflow
• Claims and reimbursements
• Leave management
• Company news
• OrbitChirp social feed
• Events workspace
• Document Library (categories, upload, search, versions, audit)
• Notifications (in-app, email, Teams) and delivery audit trail
• Settings and preferences APIs

Tech Stack

• FastAPI
• Uvicorn
• MongoDB (pymongo)
• JWT (PyJWT)
• Multipart upload (python-multipart)
• S3-compatible storage (boto3)
• PDF text extraction/indexing (pypdf)

Project Structure

• app/main.py: API routes and orchestration
• app/core/: config, DB bootstrap, seed data, utils
• app/services/: auth and city search helpers
• app/data/cities.json.gz: city autocomplete dataset
• scripts/: DB cleanup and local MinIO helpers

Prerequisites

• Python 3.11+
• MongoDB running locally or reachable via URI
• Optional: MinIO/S3-compatible storage for documents

Setup

cd orbit-server
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

Run

uvicorn app.main:app --reload --host 127.0.0.1 --port 4000

Health check:

• GET http://127.0.0.1:4000/api/health

Environment Variables

Primary values in .env.example:

• MongoDB: MONGO_URI, MONGO_DB
• JWT: JWT_SECRET, JWT_ALGORITHM, JWT_EXPIRES_HOURS
• Domain controls: DEFAULT_ACCEPTED_DOMAINS, ALLOW_ANY_DOMAIN
• Notification channels:
  • SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, SMTP_FROM_EMAIL, SMTP_USE_TLS
  • TEAMS_WEBHOOK_URL
  • ORBIT_PORTAL_BASE_URL
• S3 storage:
  • S3_ENDPOINT_URL, S3_REGION, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_BUCKET, S3_FORCE_PATH_STYLE

Note: notification channel settings can also be managed in Orbit Settings UI.

Security Model

• JWT middleware protects all /api/* routes except:
  • GET /api/health
  • POST /api/auth/session
• Role-based behavior supported for:
  • employee, supervisor, admin, super_admin
• prashant@evolvussolutions.com is seeded/treated as super admin in current setup.

Data and Seeding

• Database is auto-seeded on first startup.
• Seed includes base settings, employees, projects, and starter dashboard data.

Document Library

• Stores metadata/versioning in MongoDB.
• Stores files in S3-compatible storage.
• Supports markdown and PDF.
• Extracts/indexes searchable text for document search.
• Maintains audit timeline and activity feed.

Notifications and Audit

• In-app notifications stored per user.
• Optional email and Teams delivery based on user preferences.
• Delivery attempts are audited with success/failure and error details.

Utility Scripts

• Clean Orbit collections:

python scripts/cleanup_orbit_db.py --yes

• Drop full Orbit DB:

python scripts/cleanup_orbit_db.py --drop-db --yes

• Local MinIO helpers:

scripts/start_minio_local.sh
scripts/stop_minio_local.sh

API Notes

All APIs are exposed under /api. The frontend expects this server on port 4000 during development.

One-Click Docker Deployment (Portal + Server + MongoDB + MinIO + HTTPS)

Use this when you want the full Orbit stack on a server with one command.

Prerequisite folder layout:

• ../corp-portal must exist next to orbit-server (same parent folder).

1. Run installer:

./scripts/install-orbit-stack.sh

Installer behavior:

• Prompts configuration questions (domain, TLS email, Azure IDs, JWT, SMTP, Teams, MinIO, etc.)
• Writes/updates .env.orbit
• Builds and starts the full stack

This starts:

• caddy (automatic TLS with Let's Encrypt)
• orbit-portal (Nginx serving frontend, internal only)
• orbit-server (FastAPI)
• mongodb
• minio

Manual commands:

docker compose -f docker-compose.orbit.yml --env-file .env.orbit up -d --build
docker compose -f docker-compose.orbit.yml --env-file .env.orbit down

DNS and firewall requirements

• ORBIT_DOMAIN must resolve to your server public IP.
• Open inbound port 443 (HTTPS).
• Keep 443 directly reachable for ACME TLS-ALPN certificate validation.
• For Azure login, register redirect URI:
  • https://<your-domain>

Firewall hardening checklist

Use only required inbound ports:

• 443/tcp from internet (Orbit HTTPS)
• 22/tcp from your admin IP only (SSH)
• Do not expose 4000, 9000, 9001, or 27017 publicly.

Local Linux host with UFW:

# default deny
sudo ufw default deny incoming
sudo ufw default allow outgoing

# allow SSH only from your IP (replace x.x.x.x)
sudo ufw allow from x.x.x.x to any port 22 proto tcp

# allow Orbit HTTPS
sudo ufw allow 443/tcp

# optional: remove broad SSH rule if present
sudo ufw delete allow 22/tcp || true

sudo ufw enable
sudo ufw status verbose

AWS (EC2 Security Group):

• Inbound:
  • HTTPS 443 source 0.0.0.0/0 (and ::/0 if IPv6)
  • SSH 22 source <your-admin-ip>/32
• No other inbound rules.

Azure (NSG):

• Inbound allow:
  • TCP 443 source Any
  • TCP 22 source <your-admin-ip>/32
• Keep default deny for all others.

GCP (VPC Firewall):

• Create allow rules:
  • tcp:443 target Orbit VM tags
  • tcp:22 source <your-admin-ip>/32
• Remove or disable wide-open SSH rules.

Post-deploy verification:

# from server
sudo ss -tulpn | rg ':443|:4000|:9000|:9001|:27017'

# from external machine
nc -zv <your-domain-or-ip> 443

GitHub Actions Release Pipeline

This repo includes:

• .github/workflows/release-image-and-install-pack.yml

On tag push (for example v1.0.0) it:

1. Builds/pushes ghcr.io/<owner>/orbit-server:v1.0.0
2. Generates orbit-install-pack-v1.0.0.zip
3. Attaches the install pack to GitHub Release assets

Install pack uses prebuilt images (no source required for testers) and includes:

• docker-compose.yml
• install.sh / uninstall.sh
• .env.example
• Caddyfile
• README.txt