Wecycle

The campus circular economy, in one app. Share what you don't use, ask for what you need, and keep good stuff out of landfills — built for the Manipal (MAHE) community.

Live: wecycle.page · Android: Capacitor shell (page.wecycle.app)

Engineers: start with HANDOFF.md. The backend moved from Supabase to Appwrite in September 2026, and the code still looks like it talks to Supabase. The handoff explains why, and how to add APIs safely.

---

What's inside

Surface	What it does
Marketplace	Share items (free / swap / borrow / sell) and post requests, with categories, photos, saves, and per-listing response threads
Services & Opportunities	Offer or find services and opportunities across a compensation spectrum — volunteer, free, or paid with price bands
Events	Community events with RSVP, custom registration forms (a full Google-Forms-style builder: MCQ, checkboxes, file/PDF upload, and more), and organizer insights (views, saves, RSVPs, per-question response breakdowns, CSV export)
Lost & Found	Report lost or found items, claim and return flows
Inventory	Community-owned items members can borrow
Storefronts	Every member has a public storefront collecting their listings
Direct messages	Private one-to-one chat, started from any post or profile — realtime, read receipts, block and report. Text only for now. See HANDOFF.md
Alerts	"Tell me when someone posts X" — matched server-side, delivered in-app and via a push queue
Impact	Per-user and per-community impact scores, CO₂ and money saved, leaderboards

Everything runs in two modes: live (Appwrite in production, Supabase as the rollback path) and demo (local, no backend needed) — so the app is fully explorable without any configuration.

Tech stack

• Web: Next.js 13 App Router (client-first SPA), React 18, TypeScript
• Backend: Appwrite Cloud — TablesDB, Accounts, Storage, Realtime. Reached through an adapter that keeps the Supabase client's API, so supabase.from(...) in the code is Appwrite underneath. Supabase remains configured as the rollback path — see HANDOFF.md
• Native: Capacitor 8 Android and iOS shells wrapping a static export
• Hosting: Vercel, custom domain wecycle.page

Quick start

npm install
npm run dev

Open http://localhost:3000. With no environment configured the app runs in demo mode — every screen works against local fixture data, so you can explore the whole product immediately.

To run against a real backend, copy the template — it is pre-filled for the production Appwrite project, whose endpoint and project id are public by design:

cp .env.local.example .env.local

Variable	Required	Purpose
NEXT_PUBLIC_SUPABASE_URL	for live mode	Supabase project URL
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY	for live mode	Publishable API key (legacy NEXT_PUBLIC_SUPABASE_ANON_KEY also honored). Safe to ship — RLS enforces every boundary server-side
NEXT_PUBLIC_SITE_URL	optional	Canonical origin (defaults to https://wecycle.page)
REMOVE_BG_API_KEY	optional	Server-only key for the background-removal proxy (/api/remove-background)

The full variable list, and which are secret, is in HANDOFF.md. To stand up the schema on a fresh Appwrite project, see db/appwrite/README.md. The Supabase migrations in supabase/migrations/ are kept as history.

Repository map

app/                    Routes: the SPA shell (page.tsx), mission, privacy, terms,
                        delete-account, s/[id] share pages, api/remove-background
components/             42 screen & UI components (screens are full-page surfaces)
components/forms/       Post/submit modals + the event form builder
lib/                    Data & domain logic — auth context, live data layer,
                        demo stores, email gate, password rules, event forms,
                        opportunities, analytics, platform helpers
supabase/migrations/    Complete schema history, exported from the live project
supabase/functions/     Edge functions (push-fanout)
android/                Capacitor Android project (the shipped native shell)
scripts/                build-cap.sh (static export for native), helpers
docs/                   Architecture, auth, backend, Android, deployment docs
public/                 Brand assets, banners, icons
play-assets/            Play Store listing assets

How it fits together

• One shell, many screens. app/page.tsx hosts the whole product as client-side screens (feed, marketplace, events, …) with dedicated full pages for focused tasks — form building, form filling, password changes — rather than stacked modals.
• Auth is password-based (Appwrite Accounts). Every migrated member kept their password — their bcrypt hashes were imported directly. Accounts are Manipal-only: checked in the sign-up form, and on the server by ensure_profile, which refuses a profile to anyone else. Account creation itself is not yet gated server-side — see HANDOFF.md.
• Permissions replace RLS. Tables grant create to members; ownership is stamped per row; counters and anything touching another member's row go through /api/rpc, which holds the server key. Details: HANDOFF.md.
• The native app is the same web app, statically exported and bundled into a Capacitor WebView — data comes from the backend at runtime, and server routes are reached through apiBase(). Details: docs/android.md.

Documentation

Doc	Covers
docs/architecture.md	App structure, screen model, data layers, design language
docs/auth.md	The full auth model: passwords, OTP confirmation, the Manipal gate, reset flow, anti-enumeration
HANDOFF.md	Start here. Current architecture, the backend adapter, how to add an API, permissions, keys, known gaps
docs/backend.md	Historical — the Supabase backend as it was before the September 2026 move
docs/android.md	Building the native Android app, signing, Play readiness
docs/deploying.md	Web deploys, domain/DNS, auth email (SMTP) operations
docs/play-console-launch.md	Play Console launch runbook (closed testing)
docs/app-update-flow.md	Which changes reach the installed apps on their own, and which need a release
db/appwrite/README.md	Where the backend is going — Appwrite Education: the schema, the account/data import, and the media move

Development

npm run dev        # dev server on :3000
npm run build      # production build (what Vercel runs)
npm run build:cap  # static export for the native shell (CAP_EXPORT=1)
npm run cap:sync   # export + sync into android/

TypeScript is strict; there are no generated-code exceptions in app/, components/, or lib/.

License

All rights reserved for now — this repository is public for transparency and review. If you want to build on it, open an issue and ask.