Skip to main content

Architecture Overview

Tellus EHS is built as a modern, cloud-native SaaS platform.

High-Level Architecture​

                                    ┌──────────────────┐
                                    │   CDN / Static   │
                                    │   (Netlify/CF)   │
                                    └────────┬─────────┘
                                             │
┌─────────────┐     ┌──────────────┐    ┌────┴────┐
│   Browser   │────▶│   Frontend   │───▶│   API   │
│   (React)   │     │   (Vite)     │    │ Gateway │
└─────────────┘     └──────────────┘    └────┬────┘
                                             │
                    ┌────────────────────────┼────────────────────────┐
                    │                        │                        │
              ┌─────┴─────┐          ┌───────┴───────┐        ┌──────┴──────┐
              │  Backend  │          │  Background   │        │   Auth      │
              │  Service  │          │   Service     │        │ (Supabase)  │
              │ (FastAPI) │          │   (Python)    │        │             │
              └─────┬─────┘          └───────┬───────┘        └─────────────┘
                    │                        │
                    └────────────┬───────────┘
                                 │
                    ┌────────────┼────────────┐
                    │            │            │
              ┌─────┴─────┐ ┌────┴────┐ ┌─────┴─────┐
              │ PostgreSQL│ │   S3    │ │  OpenAI/  │
              │(DigitalO) │ │ Storage │ │ Anthropic │
              └───────────┘ └─────────┘ └───────────┘

Technology Stack​

Frontend​

  • React 18 with TypeScript
  • Vite for build tooling
  • Tailwind CSS for styling
  • Redux Toolkit for state management
  • React Router for navigation

Backend​

  • FastAPI (Python 3.11+)
  • SQLAlchemy ORM
  • Pydantic for validation
  • Alembic for migrations
  • Supabase for authentication

Infrastructure​

  • PostgreSQL (DigitalOcean managed)
  • AWS S3 for file storage
  • AWS SQS for job queues
  • Netlify/Vercel for frontend hosting
  • DigitalOcean App Platform for backend

AI/ML​

  • OpenAI GPT-4 for SDS parsing
  • Anthropic Claude (alternative)
  • PubChem API for chemical data

Core Design Principles​

1. Multi-Tenancy​

  • Complete data isolation per company
  • company_id scoping on all tables
  • Tenant context in every request

2. RBAC (Role-Based Access Control)​

  • System roles (Admin, Manager, Employee)
  • Custom company roles
  • Fine-grained permissions
  • Tier-based feature access

3. Layered Architecture​

┌─────────────────────────────────────┐
│           API Layer                 │  ← Route handlers
├─────────────────────────────────────┤
│         Service Layer               │  ← Business logic
├─────────────────────────────────────┤
│        Repository Layer             │  ← Data access
├─────────────────────────────────────┤
│           Database                  │  ← PostgreSQL
└─────────────────────────────────────┘

4. Event-Driven Processing​

  • Background job processing
  • Async SDS parsing
  • Webhook notifications

Key Subsystems​

Authentication​

  • JWT tokens via Supabase
  • Session management
  • MFA support (Pro tier)
  • SSO integration (Pro tier)

Chemical Management (ChemIQ)​

  • Product catalog
  • Inventory tracking
  • SDS document storage
  • Hazard classification

Background Processing​

  • SDS parsing queue
  • Chemical enrichment
  • PPE recommendation generation
  • Report generation

Scalability Considerations​

  • Stateless API servers (horizontal scaling)
  • Connection pooling for database
  • CDN for static assets
  • Background job workers (scale independently)
  • S3 for unlimited file storage

Security​

  • HTTPS everywhere
  • JWT token authentication
  • Row-level security (via company_id)
  • Encrypted secrets (environment variables)
  • Audit logging for compliance