Deployment pipeline verified.
EcoTag is a mobile app that estimates the carbon footprint of clothing items by scanning garment care tags. Point your phone camera at a clothing label, and EcoTag uses AI to read the materials, manufacturing origin, and care instructions, then calculates total CO2 emissions across the garment's lifecycle.
The project has two main parts:
backend/-- A Node.js server that receives clothing tag images, sends them to a vision-language model (Google Gemini by default, OpenAI optional) for analysis, and calculates CO2 emissions.mobile/-- A React Native (Expo) mobile app with a camera interface for scanning tags and viewing results.
- Features & Pages
- Requirements
- Choosing a VLM Provider
- Backend Setup
- Mobile App Setup
- Using the App
- Troubleshooting
- Android Support
- Running Without an API Key (Mock Mode)
A guided two-step walkthrough that introduces new users to the app's core workflow: scanning a garment tag and viewing the results.
A dashboard showing your two most recent scans with their CO2 values and EcoRatings. Provides quick access to the scanner and a "View All" link to your full closet history.
Point your phone camera at a clothing care tag and take a photo, or pick an image from your photo library. The app sends the image to the backend, where a vision-language model extracts the materials, country of origin, and care instructions.
After a scan, the app displays a detailed emissions breakdown covering material production, manufacturing, transport, care, and end-of-life. Each garment receives an EcoRating (Poor, Average, or Good) based on how its CO2 footprint compares to industry benchmarks, shown as a color-coded badge and gauge.
Browse all your scanned garments or just the ones you've saved. Search by name, view material composition and emissions data, and delete items you no longer need.
Select multiple garments to compare their environmental impact side-by-side. Each card shows its EcoRating pill, and the view highlights your overall wardrobe eco-score alongside the highest-impact items.
Background on the Benevolent Bandwidth Foundation and the principles behind EcoTag.
You need the following installed on your Mac:
- Node.js v18 or newer -- Download the LTS version from nodejs.org, run the installer, then verify with
node --versionin Terminal. - Git -- Run
git --versionin Terminal. If not installed, macOS will prompt you to install the Command Line Developer Tools.
EcoTag reads clothing tags using a vision-language model (VLM). Two providers are supported; pick one before running the backend.
| Provider | VLM_PROVIDER |
Default VLM_MODEL |
API key env var |
|---|---|---|---|
google |
gemini-2.5-pro |
GOOGLE_GENERATIVE_AI_API_KEY |
|
| OpenAI | openai |
gpt-4o |
OPENAI_API_KEY |
Selection happens at server start via environment variables in backend/.env. To switch providers, edit the env file and restart the backend -- there is no per-request override.
Note: Both providers are pay-per-use. Each tag scan costs a fraction of a cent on Gemini Pro or a few cents on GPT-4o.
- Sign in at Google AI Studio
- Click "Create API key"
- Copy the key -- you'll paste it into
backend/.envin the next section.
- Create an account (or sign in) at platform.openai.com
- Go to API keys and click "Create new secret key"
- Name it (e.g., "EcoTag") and click Create
- Copy the key immediately -- it starts with
sk-proj-and won't be shown again
cd ecotag/backendnpm installcp .env.example .envOpen backend/.env in any text editor and fill in the key for the provider you chose above.
For Gemini (default):
VLM_PROVIDER=google
GOOGLE_GENERATIVE_AI_API_KEY=your-key-hereFor OpenAI:
VLM_PROVIDER=openai
OPENAI_API_KEY=sk-proj-your-key-hereOverride the default model with VLM_MODEL=... if you want a different one (e.g., gemini-2.5-flash).
node server.jsYou should see:
Server running on port 3001
Leave this Terminal window open -- the server needs to stay running. Open a new Terminal window/tab for the mobile app.
There are two ways to run the mobile app:
- Option A: iOS Simulator on your Mac (no physical iPhone needed)
- Option B: Expo Go on a real iPhone (full camera access)
- Open the App Store on your Mac and search for "Xcode"
- Click Get / Install (large download, ~10-12 GB)
- Once installed, open Xcode once to accept the license agreement and install additional components
- In Xcode, go to Xcode > Settings > Platforms
- If no iOS simulator is listed, click + and download the latest iOS version
Already have Xcode? Verify simulators are available with
xcrun simctl list devices availablein Terminal.
Open a new Terminal window (keep the backend running):
cd ecotag/mobile
npm install
npx expo start --iosThis starts the Expo dev server, opens the iOS Simulator, and installs the app. The first launch may take a couple of minutes.
Note: The iOS Simulator has no real camera. Use the gallery icon in the app to pick a photo of a clothing tag from your Mac's photo library instead.
Download "Expo Go" from the App Store on your iPhone.
Make sure your iPhone and Mac are on the same Wi-Fi network.
Open a new Terminal window (keep the backend running):
cd ecotag/mobile
npm install
npx expo startA QR code will appear in Terminal. Open the Camera app on your iPhone, point it at the QR code, and tap the notification to open the app in Expo Go.
Backend connection: The app automatically detects your Mac's IP address from the Expo dev server and connects to the backend on port 3001 -- no manual configuration needed.
If the app can't reach the backend, auto-detection may not work on your network. Find your Mac's IP (System Settings > Wi-Fi > Details, or
ipconfig getifaddr en0in Terminal) and start with:EXPO_PUBLIC_API_BASE_URL=http://YOUR_IP:3001 npx expo start
- Home -- View your most recent scans with their CO2 values and EcoRatings, and jump straight to the scanner
- Scan -- Open the Scan tab, point your camera at a clothing tag, and take a photo (or pick one from your photo library)
- Results -- The app sends the image to the backend for AI analysis, then shows the extracted materials, country of origin, care instructions, a CO2 emissions breakdown, and an EcoRating. You can save a scan to your closet from the results screen.
- Closet -- Browse your saved garments or all recent scans. Search, view details, and delete items.
- Comparison -- Select multiple garments to compare their environmental impact side-by-side with EcoRating badges
- Make sure the backend is still running (
Server running on port 3001in Terminal) - If on a real iPhone, confirm your phone and Mac are on the same Wi-Fi
- If auto-detection isn't working, set
EXPO_PUBLIC_API_BASE_URLexplicitly (see Option B)
- The API key for your selected
VLM_PROVIDERis likely missing or invalid - For
VLM_PROVIDER=google: check thatGOOGLE_GENERATIVE_AI_API_KEYis set inbackend/.env - For
VLM_PROVIDER=openai: check thatOPENAI_API_KEYis set inbackend/.env(starts withsk-proj-, no extra spaces) - The model id in
VLM_MODELmay not exist for the selected provider
- Make sure Xcode has been opened at least once and components are installed
- Verify a simulator runtime is downloaded (Xcode > Settings > Platforms)
- Confirm Node.js v18+ is installed (
node --version) - Try removing
node_modulesand reinstalling:rm -rf node_modules && npm install
Android has not been tested yet. The app includes Android configuration in app.json, but it has not been verified on Android devices or emulators. This is planned for a future milestone.
To try the app without a Gemini or OpenAI key, start the backend in mock mode:
cd backend
MOCK_OCR=1 node server.jsThis returns fake (but realistic-looking) tag data instead of calling the VLM. Useful for testing the full app flow without any API costs.