Skip to main content

Getting Started

This guide helps developers get up and running with the Tellus EHS codebase.

Prerequisites​

  • Node.js 18+ (for frontend)
  • Python 3.11+ (for backend)
  • PostgreSQL 14+ (or access to development database)
  • Git for version control

Repository Structure​

tellus/
├── tellus-ehs-hazcom-service/    # FastAPI backend (Python)
├── tellus-ehs-hazcom-ui/         # React frontend (TypeScript)
├── tellus-ehs-background-service/ # Background job processor
├── tellus-docs/                   # Documentation (this site)
└── docs/                          # Legacy documentation

Quick Setup​

Backend Service​

cd tellus-ehs-hazcom-service

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set up environment variables
cp .env.example .env
# Edit .env with database and Supabase credentials

# Run development server
python -m app.main
# OR
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

API docs available at: http://localhost:8000/api/docs

Frontend​

cd tellus-ehs-hazcom-ui

# Install dependencies
npm install

# Run development server
npm run dev

Frontend available at: http://localhost:5174

Environment Variables​

Backend (.env)​

DATABASE_URL=postgresql://user:pass@host:5432/dbname
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_KEY=your-service-key
JWT_SECRET_KEY=your-jwt-secret
ALLOWED_ORIGINS=http://localhost:5174

Frontend (.env.local)​

VITE_API_URL=http://localhost:8000
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your-anon-key

Database Migrations​

cd tellus-ehs-hazcom-service

# Generate new migration
alembic revision --autogenerate -m "description"

# Apply migrations
alembic upgrade head

# Rollback one version
alembic downgrade -1

# View current version
alembic current

Code Quality​

Backend​

black app/          # Format code
isort app/          # Sort imports
flake8 app/         # Lint
mypy app/           # Type checking
pytest              # Run tests

Frontend​

npm run lint        # ESLint
npm run build       # Type check + build

Architecture Overview​

Backend (FastAPI)​

  • API Layer (app/api/v1/) - Route handlers
  • Service Layer (app/services/) - Business logic
  • Data Layer (app/db/models/) - SQLAlchemy models
  • Schema Layer (app/schemas/) - Pydantic models

Frontend (React + TypeScript)​

  • Pages (src/pages/) - Route components
  • Components (src/components/) - Reusable UI
  • Services (src/services/) - API communication
  • Store (src/store/) - Redux state
  • Types (src/types/) - TypeScript definitions

Key Patterns​

  • Dependency Injection via FastAPI's Depends()
  • Multi-tenancy via company_id scoping
  • RBAC with roles and permissions
  • Supabase Auth for authentication

Next Steps​

  1. Review Project Structure
  2. Set up Local Development
  3. Explore Implementation Guides