Project Structure

Repository Overview

The Tellus platform is organized as a monorepo:

tellus/
├── tellus-ehs-hazcom-service/     # Main backend API
├── tellus-ehs-hazcom-ui/          # Frontend application
├── tellus-ehs-background-service/ # Background job processor
├── tellus-docs/                    # Documentation site
├── docs/                           # Legacy documentation
└── CLAUDE.md                       # AI assistant context

Backend Service Structure

tellus-ehs-hazcom-service/
├── alembic/                  # Database migrations
│   ├── versions/             # Migration files
│   └── env.py
├── app/
│   ├── api/
│   │   └── v1/               # API routes by domain
│   │       ├── auth/
│   │       ├── chemiq/       # Chemical inventory
│   │       ├── companies/
│   │       └── users/
│   ├── core/                 # Core configuration
│   │   ├── config.py
│   │   └── constants.py
│   ├── db/
│   │   ├── models/           # SQLAlchemy models
│   │   ├── repositories/     # Data access layer
│   │   └── session.py
│   ├── schemas/              # Pydantic schemas
│   │   ├── chemiq/
│   │   └── user.py
│   ├── services/             # Business logic
│   │   ├── chemiq/
│   │   └── onboarding_service.py
│   └── utils/                # Helper functions
├── tests/                    # Test files
├── requirements.txt
└── .env                      # Environment variables

Key Directories

Directory	Purpose
app/api/v1/	FastAPI route handlers
app/db/models/	SQLAlchemy ORM models
app/schemas/	Pydantic request/response models
app/services/	Business logic layer
app/core/	Configuration and constants
alembic/versions/	Database migration scripts

Frontend Structure

tellus-ehs-hazcom-ui/
├── public/                   # Static assets
├── src/
│   ├── components/           # Reusable UI components
│   │   ├── common/
│   │   └── MainLayout.tsx
│   ├── contexts/             # React contexts
│   ├── pages/                # Route-level components
│   │   ├── auth/
│   │   ├── chemiq/           # Chemical inventory pages
│   │   │   ├── inventory/
│   │   │   └── library/
│   │   ├── onboarding/
│   │   └── settings/
│   ├── services/             # API communication
│   │   └── api/
│   ├── store/                # Redux state
│   ├── types/                # TypeScript definitions
│   └── utils/                # Helper functions
├── index.html
├── package.json
├── tailwind.config.js
├── tsconfig.json
└── vite.config.ts

Key Directories

Directory	Purpose
src/pages/	Route components (page-level)
src/components/	Reusable UI components
src/services/api/	API client functions
src/store/	Redux store and slices
src/types/	TypeScript type definitions

Background Service Structure

tellus-ehs-background-service/
├── app/
│   ├── core/                 # Configuration
│   ├── db/
│   │   ├── models/
│   │   └── repositories/
│   ├── services/             # Job processors
│   │   ├── sds_parse/        # SDS parsing jobs
│   │   ├── chemical_enrichment/
│   │   └── ppe_recommendation/
│   └── utils/
├── jobs/                     # Cron job definitions
└── requirements.txt

Module Organization

ChemIQ (Chemical Inventory)

Backend:

• app/api/v1/chemiq/ - API routes
• app/services/chemiq/ - Business logic
• app/db/models/chemiq_*.py - Database models
• app/schemas/chemiq/ - Pydantic schemas

Frontend:

• src/pages/chemiq/ - UI pages
• src/types/chemiq.ts - Type definitions

AdminHQ (Administration)

Backend:

• app/api/v1/companies/, users/ - API routes
• app/services/company_service.py - Business logic
• app/db/models/company.py, user.py - Models

Frontend:

• src/pages/settings/ - Settings pages
• src/pages/onboarding/ - Onboarding flow