TrustAdda Docs

Overview

TrustAdda is a free, open-source platform for licensed hostels, PGs and other community living spaces. It runs trust-based self-service stores and gives owners a maintenance dashboard for stock, refill requests and resident feedback.

Frontend: React (Vite), TypeScript, Tailwind CSS, shadcn/ui
Backend: Express on Node.js, Drizzle ORM
Database: PostgreSQL (Neon, Render or local), or in-memory for quick trials
Mobile: Capacitor (Android)

Getting started

You need Node.js 24 or newer. PostgreSQL is optional for a first look.

git clone https://github.com/karriprakash/TrustAdda.git
cd TrustAdda
npm install
npm run dev

Open http://localhost:5000. Without a database, data lives in memory and resets when the server restarts.

Use a real database

Create a .env file in the project root, then push the schema:

DATABASE_URL=postgresql://user:password@localhost:5432/trustadda
USE_DATABASE=true
SESSION_SECRET=change-me-to-a-long-random-string

npm run db:push

Configuration

Variable	Required	What it does
`DATABASE_URL`	For Postgres	PostgreSQL connection string
`USE_DATABASE`	For Postgres	Set to `true` to use Postgres instead of in-memory storage
`SESSION_SECRET`	Yes (production)	Secret used to sign login sessions
`PORT`	No	Port to listen on (default 5000)
`SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASS`	For email login	Mail server used to send login one-time codes

Deploy

Render (recommended)

Push your fork to GitHub.
In the Render dashboard choose New → Blueprint and select the repo. render.yaml creates the web service and a free Postgres database.
Add USE_DATABASE=true to the service's environment variables so it uses Postgres.
Optionally add a custom domain under Settings → Custom Domains and create the DNS records Render shows you.

The app needs a long-running Node server and a database, so use a host like Render, Railway or a VPS. Static hosts only serve the frontend.

Android app

npm run build
npx cap sync android
npx cap open android

This opens the project in Android Studio, where you can run it on a device or build an APK.

Using the dashboard

Store points

Each physical place residents buy from is a store point. There are three types: sachet stands, vending machines and digital kirana counters. Give each one a name, location and UPI ID for payments.

Inventory

Add items with a category (laundry, personal care, beverages, snacks, kirana, medicine, electronics), price and quantity. Duplicate detection warns you before adding the same item twice.

Orders

Residents check out by UPI QR or “trust later”. Every order is recorded with its store, items and payment method.

Refill requests

When a stand or machine runs empty, residents send a refill request with its location. It shows as pending until staff mark it completed.

Feedback

Residents can send suggestions, issues and ideas. Use these to spot maintenance problems early.

Admins

Admins sign in by email one-time code and can add or remove other admins and change settings.

API reference

The server exposes a JSON API under /api.

Method	Path	Purpose
GET / POST	`/api/items`	List or create items
GET / PUT / DELETE	`/api/items/:id`	Read, update or delete an item
POST	`/api/items/check-duplicate`	Check whether an item already exists
GET / POST	`/api/stores`	List or create store points
GET / POST	`/api/orders`	List or record orders
GET / POST	`/api/refill`	List or create refill requests
PATCH	`/api/refill/:id/resolve`	Mark a refill request completed
GET / POST	`/api/feedback`	List or send feedback
GET / POST	`/api/machine-inquiries`	Requests to set up a new stand or machine
GET / POST / DELETE	`/api/admin/…`	Admin config, admins and settings (admin only)

MCP server

TrustAdda hosts an open-source Model Context Protocol server so AI assistants such as Claude can connect to it. It currently offers starter tools (ping, echo); more will follow.

claude mcp add --transport http cc-ai-cam https://mcp.trustadda.com/mcp

Source: github.com/karriprakash/cc-ai-cam-mcp

Contributing

Contributions of every size are welcome — code, docs, translations, or ideas from people running real hostels.

Fork the repo and create a branch.
Run npm run check to type-check before you push.
Open a pull request describing what changed and why.

License

TrustAdda is released under the MIT License. You can use, copy, modify and distribute it, including commercially, as long as the copyright notice is kept.