diff --git a/README.md b/README.md index c2878be..a4a284e 100644 --- a/README.md +++ b/README.md @@ -1,133 +1,109 @@ -### opensociety +# OpenSociety -**opensociety** is a privacy-first, open-source society management platform — an alternative to MyGate and NoBrokerHood for gated communities. The code is open and your data is portable: you own your deployment. +**A little closer to home.** -## Tech Stack +OpenSociety is an ad-free, open-source app for apartment communities. Welcome guests, keep up with neighbourhood notices, track maintenance bills, and take care of everyday requests from one calm, thoughtfully designed place. -**Frontend:** -- Web: [TanStack Start](https://tanstack.com/start) (React) + TanStack Query -- Mobile: [Expo](https://expo.dev) Router (React Native, SDK 57) + TanStack Query +Residents and gate staff use the iPhone and Android app. Community administrators manage the society from a web dashboard. Each society runs its own API and database, keeping its records separate and its deployment under its control. -**Backend:** -- API: [Hono](https://hono.dev) on Node 22 for shared hosting; Cloudflare Workers adapter also available -- Database: [Neon Postgres](https://neon.tech) via [Drizzle ORM](https://orm.drizzle.team) (neon-http driver) -- Shared contracts: Zod (`@opensociety/shared`) +[Explore the app](#a-look-inside) · [Availability](#availability) · [Run locally](#run-locally) · [Deployment guide](deploy/README.md) · [Contribute](#contributing) -**Authentication:** -- [Clerk](https://clerk.com) (web + mobile), authn-only with a local user mirror. Resident OTP uses Clerk's built-in phone OTP — no separate SMS provider for auth. +## A look inside -**Storage & Services:** -- Photos/documents: Cloudflare R2 -- Push notifications: Expo Push +These are actual native app captures from iPhone and Android simulators, using fictional demo data. Select an image to see the full-size screen. -## Architecture +
-- **Single-tenant per society:** each society runs its own API + database instance (no `society_id`; a single `society_config` row). Complete data isolation. -- **Shared mobile app:** one app across all societies (App Store + Play Store). +*Resident home (iPhone) · Guest pass (Android) · Notices (iPhone)* -See `BLOCKING_DECISIONS.md` (in the Obsidian notes) for the rationale behind tenancy, host, auth, and MVP-scope decisions. +A clear view of bills and payments, the people who help at home, and arrivals at the gate. -## Monorepo + -``` -apps/ - api Hono API with Node and Cloudflare Workers adapters - web TanStack Start admin dashboard - mobile Expo Router app (residents + guards) -packages/ - db Drizzle schema + migrations (Neon) - shared Zod contracts shared across api/web/mobile - typescript-config shared tsconfig bases -``` - -## Quickstart - -Use Node 22 and the pinned pnpm 10 workspace install. Local development runs directly on the Mac; Docker builds and container checks run in GitHub Actions. - -```sh -pnpm install --frozen-lockfile -cp apps/api/.env.example apps/api/.env -cp apps/web/.env.example apps/web/.env -# Fill in the development Neon/Clerk values, then start both applications: -pnpm dev -``` +*Bills (Android) · Household help (iPhone) · Gate desk (Android)* -Turborepo builds the shared and database packages before starting the Node API on port 8787 and the web dashboard on port 3000. Its watcher rebuilds workspace dependencies and restarts affected applications when files change. Open **http://localhost:3000/admin**. Start the mobile app separately with `pnpm --filter @opensociety/mobile start` when needed. +## Everyday community life -Run `pnpm build`, `pnpm check-types`, `pnpm lint`, and `pnpm test` from the root. These reuse the workspace install and Turbo cache. `pnpm --filter @opensociety/api dev:worker` remains available for the Workers adapter. - -### Environment +| For | What you can do | +| --- | --- | +| **Residents** | Pre-approve guests and share QR passes, approve or deny visitors, read notices, view bills and payment history, raise maintenance tickets, and manage household help and vehicles. | +| **Gate staff** | Register visitors, scan passes or enter codes, check people in and out, verify vehicles, and record duty attendance. Visitor registration can queue while offline. | +| **Administrators** | Manage apartments and resident approvals, gate staff, notices, billing, expenses, maintenance tickets, parking, and reports from the web dashboard. | -Copy the example env files and fill in real values (all are gitignored): +The mobile app supports English and Hindi, system text scaling, and layouts for smaller screens. Additional regional languages are deferred. -``` -cp apps/api/.env.example apps/api/.env # DATABASE_URL, CLERK_* (Node API) -cp apps/web/.env.example apps/web/.env # VITE_API_URL, VITE_CLERK_PUBLISHABLE_KEY -``` +## Availability -Per-society secrets (`DATABASE_URL`, `CLERK_*`, R2) go in `apps/api/.dev.vars` for local Workers development. Node hosting uses runtime environment variables. See [the deployment guide](deploy/README.md) for container builds, configuration, migrations, scheduled jobs, and rollback. +**OpenSociety is preparing for its first pilot.** The mobile design is implemented and reviewed on iPhone and Android simulators. Public hosting and App Store / Google Play distribution are still pending, along with physical-device, screen-reader, and live-service acceptance checks. -Clerk sessions authenticate web and mobile requests. The API accepts the local `x-user-id` fallback only when no Clerk secret is configured. Keep development identity overrides out of preview and store builds. +You can explore the code and run a development instance today. A society deployment needs its own database, authentication configuration, storage, and hosting; running those services can incur costs. Start with the [deployment guide](deploy/README.md) and [mobile release guide](docs/mobile.md) when preparing a pilot. -## Mobile builds +## Run locally -EAS project: [ankitsejwal/opensociety](https://expo.dev/accounts/ankitsejwal/projects/opensociety). Run EAS commands from `apps/mobile`. `eas.json` provides development, iOS simulator, preview APK/ad-hoc, TestFlight, and Play internal profiles. Development installs use `com.opensociety.app.dev`; preview and store installs use `com.opensociety.app`. EAS manages store build numbers. The post-install hook builds the shared workspace package before Metro runs. +Use **Node 22** and **pnpm 10.0.0**. The pnpm version is pinned in `package.json`. Development uses pnpm workspaces and Turborepo; no local Docker setup is required. ```sh -eas build --platform ios --profile simulator -eas build --platform android --profile development -eas build --platform ios --profile testflight -eas build --platform android --profile play-internal +git clone https://github.com/opencore-x/opensociety.git +cd opensociety +pnpm install --frozen-lockfile +cp apps/api/.env.example apps/api/.env +cp apps/web/.env.example apps/web/.env ``` -Both developer memberships are available. OpenSociety needs its own store app records and signing/provisioning credentials. The existing Google publishing service account currently has Lucidity-only access. Configure the OpenSociety credentials in EAS and grant testing-track access for this app before submitting. Set the new App Store Connect app ID in `submit.testflight.ios.ascAppId` once Apple creates it. Play submission starts as a draft for the first Console rollout. - -Configure `EXPO_PUBLIC_API_URL` and `EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY` in each EAS environment. Preview/store builds require HTTPS and reject `EXPO_PUBLIC_DEV_USER_ID`; store profiles also require a live Clerk key. The current local `.env` is for development and cannot be used to ship the app. Android push will also need an EAS file variable `GOOGLE_SERVICES_JSON` for this app's Firebase configuration. Keep signing keys and service-account JSON outside Git. - -The manual **Mobile build** GitHub workflow requires a repository `EXPO_TOKEN` secret and waits for the selected EAS build. It does not submit automatically. After a successful store build, use `eas submit --platform ios --profile testflight --id BUILD_ID` or `eas submit --platform android --profile play-internal --id BUILD_ID`, then verify processing and tester access in the corresponding store. - -## Push notifications +Set `DATABASE_URL` in `apps/api/.env` to a development Neon database and configure matching Clerk credentials in the API and web env files. R2 credentials are needed to exercise uploads. The example database URL is a placeholder. -The service supports visitor approval/check-in alerts, notice publication (all residents or a selected tower), blocked/towed vehicle alerts, and maintenance reminders. The mobile app registers devices after permission is granted, refreshes tokens on foreground, removes registration before sign-out, and opens the relevant screen when a notification is tapped. +Supply the same development `DATABASE_URL` in your shell before applying the checked-in migrations. The database CLI does not load `apps/api/.env` automatically: -Apply migration `0023_push_delivery.sql` before enabling push. The database stores per-account tokens and a durable delivery outbox with event/device deduplication, bounded retries, Expo receipt checks, and stale/dead-token cleanup. Expo ticket acceptance is not treated as delivery. Messages can still arrive more than once if an upstream timeout occurs after Expo accepted a request. Gate messages take precedence over broadcasts; dispatch is limited to 500 messages per pass, with follow-up jobs draining larger backlogs. Terminal deliveries are retained for seven days and expired work is discarded. +```sh +pnpm --filter @opensociety/db db:migrate +pnpm dev +``` -For the current Workers adapter, provision `opensociety-push` and `opensociety-push-failed`, then deploy the queue bindings in `apps/api/wrangler.jsonc`. Queue wake-ups carry no personal data and run only while deliveries/receipts are pending. The morning reminder run also recovers outbox records whose wake-up publication failed. Monitor the dead-letter queue for repeated failures. +Open **http://localhost:3000/admin**. The Node API runs on **http://localhost:8787**. Turborepo builds shared packages before startup and rebuilds affected workspace dependencies as files change. -| Setting | Purpose | -| --- | --- | -| `PUSH_ENABLED=true` | Enable after the migration, queue bindings, and app credentials are ready; defaults to false. | -| `EXPO_ACCESS_TOKEN` | Server secret, required if enhanced push security is enabled for this EAS project. | -| `BILL_REMINDER_DAYS=-7,0,3` | Days relative to the due date; configurable per society. | -| `SOCIETY_TIME_ZONE=Asia/Kolkata` | Calendar days and morning reminder window (the first hourly run in the local 09:00 hour). | +For a local demo without Clerk, leave Clerk credentials unset, run `pnpm --filter @opensociety/db db:seed` with the development `DATABASE_URL` in your shell, and set `VITE_DEV_USER_ID=00000000-0000-0000-0000-000000000001` in `apps/web/.env` before starting the app. This seeds a development admin and sample community. Keep development identities and seed data out of deployed environments. -Configure this app's APNs credential in EAS for iOS. For Android, configure the Firebase app matching the chosen build's package ID, its `GOOGLE_SERVICES_JSON` file, and the FCM v1 service-account credential in EAS. Lucidity's app-specific credentials do not substitute for these. Rebuild the native app after changing notification credentials/configuration. Use a development or store build for testing; Expo Go does not exercise this setup. +For the Workers adapter, use `pnpm --filter @opensociety/api dev:worker` and keep local secrets in `apps/api/.dev.vars`. The default `pnpm dev` uses the Node adapter and `.env` files. -Before pilot distribution, verify on physical iOS and Android devices: permission grant/denial; foreground/background/cold-start notification taps; resident and guard event routing; tower targeting; partial/paid/cancelled bill reminders; token refresh; sign-out and account switching. Database integration tests cover queue claims, deduplication, retries, receipts, account reassignment, and dead-token removal; they do not prove delivery through APNs/FCM. +To run the iPhone or Android app, follow [mobile development](docs/mobile.md#local-development) for API addresses, environment variables, and native builds. -The shared DigitalOcean Droplet is not provisioned yet. A Node API adapter, web server, R2 S3 adapter, restart recovery, and container configuration are prepared in [the deployment guide](deploy/README.md). Store profiles still need the deployed HTTPS API and live Clerk configuration. +## How it is built -## Admin dashboard +| Part | Stack | Location | +| --- | --- | --- | +| Mobile app | Expo Router, React Native, TanStack Query | [`apps/mobile`](apps/mobile) | +| Admin dashboard | TanStack Start, React, shadcn/ui | [`apps/web`](apps/web) | +| API | Hono on Node 22; Cloudflare Workers adapter also available | [`apps/api`](apps/api) | +| Database | Neon Postgres and Drizzle ORM | [`packages/db`](packages/db) | +| Shared contracts | Zod schemas and translations | [`packages/shared`](packages/shared) | -The web app (`apps/web`) is a shadcn/ui dashboard with light + dark mode at `/admin`: +Clerk authenticates web and mobile sessions; the API maps them to local users and permissions. Each society has a separate API and database with a single society configuration. Cloudflare R2 stores photos and documents, and Expo Push handles mobile notifications. The [deployment guide](deploy/README.md) covers the Node hosting setup, scheduled jobs, migrations, and rollback. -- **Overview** — at-a-glance counts and a setup checklist -- **Society** — society configuration -- **Apartments** — add units individually or via bulk CSV import -- **Residents** — approve sign-ups (assign apartment + relation) and manage roles -- **Guards** — register gate staff, activate/deactivate -- **Visitors** — visitor logs with status filters, approve/deny -- **Notices** — publish announcements with priority and expiry +## Contributing -## CI +Bug reports, usability feedback, documentation improvements, and focused pull requests are welcome. [Open an issue](https://github.com/opencore-x/opensociety/issues) with the affected flow, expected behaviour, and reproduction steps. For mobile layout issues, include the platform, screen size, and system text size; use fictional data in screenshots. -GitHub Actions runs build + type-check on every push and PR to `main` (`.github/workflows/ci.yml`). +Before opening a code PR, run the workspace checks: -## Documentation - -- **Roadmap:** tracked in Lucidity (M0–M4 milestones) -- **Database schema:** `packages/db/schema.dbml` + generated migrations in `packages/db/drizzle/` +```sh +pnpm build +pnpm check-types +pnpm lint +pnpm test +``` ---- +CI runs these checks and builds and smoke-tests the hosting containers. For mobile UI changes, also review the app on both native platforms; a browser preview alone does not establish native layout quality. -Built with ❤️ for transparency, privacy, and community ownership. +- [Mobile design and component guidance](apps/mobile/components/README.md) +- [Mobile development, builds, and push notifications](docs/mobile.md) +- [Deployment and operations](deploy/README.md) +- [Database schema](packages/db/schema.dbml) and [migrations](packages/db/drizzle) +- [Screenshot provenance and refresh guidance](docs/screenshots/README.md) diff --git a/docs/mobile.md b/docs/mobile.md new file mode 100644 index 0000000..f0c71d2 --- /dev/null +++ b/docs/mobile.md @@ -0,0 +1,65 @@ +# Mobile development and release + +[Back to OpenSociety](../README.md) + +## Local development + +Use the root pnpm workspace install and a running development API. Create `apps/mobile/.env` (gitignored) with public development configuration: + +```dotenv +EXPO_PUBLIC_API_URL=http://localhost:8787 +EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_... +``` + +Use the same Clerk instance as the API. An Android emulator reaches the host API at `http://10.0.2.2:8787`; a physical phone needs a reachable LAN address. When working without Clerk locally, omit the publishable key and set `EXPO_PUBLIC_DEV_USER_ID` to a real development user ID. The API accepts that override only when no Clerk secret is configured. Never use development identity overrides in preview or store builds. + +From the repository root: + +```sh +pnpm --filter @opensociety/shared build +pnpm --filter @opensociety/mobile start +``` + +Open Metro with an installed development build. Build profiles and native credentials are described below. [Mobile component guidance](../apps/mobile/components/README.md) covers visual changes, text scaling, safe areas, and native review. + +## Release status + +The mobile design was reviewed on iPhone and Android simulators on 2026-10-03. The remaining release checks include physical-device acceptance, spoken VoiceOver/TalkBack testing, live authentication, and push delivery. Store distribution also requires a deployed HTTPS API and app-specific credentials. English and Hindi are available; additional regional languages are deferred. + +## Build profiles + +EAS project: [ankitsejwal/opensociety](https://expo.dev/accounts/ankitsejwal/projects/opensociety). Run EAS commands from `apps/mobile`. `eas.json` provides development, iOS simulator, preview APK/ad-hoc, TestFlight, and Play internal profiles. Development installs use `com.opensociety.app.dev`; preview and store installs use `com.opensociety.app`. EAS manages store build numbers. The post-install hook builds the shared workspace package before Metro runs. + +```sh +eas build --platform ios --profile simulator +eas build --platform android --profile development +eas build --platform ios --profile testflight +eas build --platform android --profile play-internal +``` + +Apple and Google developer memberships are available. OpenSociety still needs its own store app records, signing/provisioning credentials, and a Google publishing service account with access to this app. Configure the OpenSociety credentials in EAS and grant testing-track access for this app before submitting. Set the new App Store Connect app ID in `submit.testflight.ios.ascAppId` once Apple creates it. Play submission starts as a draft for the first Console rollout. + +Configure `EXPO_PUBLIC_API_URL` and `EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY` in each EAS environment. Preview/store builds require HTTPS and reject `EXPO_PUBLIC_DEV_USER_ID`; store profiles also require a live Clerk key. The current local `.env` is for development and cannot be used to ship the app. Android push will also need an EAS file variable `GOOGLE_SERVICES_JSON` for this app's Firebase configuration. Keep signing keys and service-account JSON outside Git. + +The manual **Mobile build** GitHub workflow requires a repository `EXPO_TOKEN` secret and waits for the selected EAS build. It does not submit automatically. After a successful store build, use `eas submit --platform ios --profile testflight --id BUILD_ID` or `eas submit --platform android --profile play-internal --id BUILD_ID`, then verify processing and tester access in the corresponding store. + +## Push notifications + +The service supports visitor approval/check-in alerts, notice publication (all residents or a selected tower), blocked/towed vehicle alerts, and maintenance reminders. The mobile app registers devices after permission is granted, refreshes tokens on foreground, removes registration before sign-out, and opens the relevant screen when a notification is tapped. + +Apply migration `0023_push_delivery.sql` before enabling push. The database stores per-account tokens and a durable delivery outbox with event/device deduplication, bounded retries, Expo receipt checks, and stale/dead-token cleanup. Expo ticket acceptance is not treated as delivery. Messages can still arrive more than once if an upstream timeout occurs after Expo accepted a request. Gate messages take precedence over broadcasts; dispatch is limited to 500 messages per pass, with follow-up jobs draining larger backlogs. Terminal deliveries are retained for seven days and expired work is discarded. + +For the current Workers adapter, provision `opensociety-push` and `opensociety-push-failed`, then deploy the queue bindings in `apps/api/wrangler.jsonc`. Queue wake-ups carry no personal data and run only while deliveries/receipts are pending. The morning reminder run also recovers outbox records whose wake-up publication failed. Monitor the dead-letter queue for repeated failures. + +| Setting | Purpose | +| --- | --- | +| `PUSH_ENABLED=true` | Enable after the migration, queue bindings, and app credentials are ready; defaults to false. | +| `EXPO_ACCESS_TOKEN` | Server secret, required if enhanced push security is enabled for this EAS project. | +| `BILL_REMINDER_DAYS=-7,0,3` | Days relative to the due date; configurable per society. | +| `SOCIETY_TIME_ZONE=Asia/Kolkata` | Calendar days and morning reminder window (the first hourly run in the local 09:00 hour). | + +Configure this app's APNs credential in EAS for iOS. For Android, configure the Firebase app matching the chosen build's package ID, its `GOOGLE_SERVICES_JSON` file, and the FCM v1 service-account credential in EAS. Credentials for another app do not substitute for these. Rebuild the native app after changing notification credentials/configuration. Use a development or store build for testing; Expo Go does not exercise this setup. + +Before pilot distribution, verify on physical iOS and Android devices: permission grant/denial; foreground/background/cold-start notification taps; resident and guard event routing; tower targeting; partial/paid/cancelled bill reminders; token refresh; sign-out and account switching. Database integration tests cover queue claims, deduplication, retries, receipts, account reassignment, and dead-token removal; they do not prove delivery through APNs/FCM. + +The shared DigitalOcean Droplet is not provisioned yet. A Node API adapter, web server, R2 S3 adapter, restart recovery, and container configuration are prepared in [the deployment guide](../deploy/README.md). Store profiles still need the deployed HTTPS API and live Clerk configuration. diff --git a/docs/screenshots/README.md b/docs/screenshots/README.md new file mode 100644 index 0000000..327ae23 --- /dev/null +++ b/docs/screenshots/README.md @@ -0,0 +1,16 @@ +# Mobile screenshots + +These are unmodified PNG captures of the native app using fictional local demo data, taken on 2026-10-03. Names, apartment details, balances, notices, and the guest pass are examples. They do not represent a live deployment. The guest QR contains the sample code `AB12CD`. + +The gallery represents the mobile design merged in [PR #111](https://github.com/opencore-x/opensociety/pull/111), with final implementation revision `ed729d7479345f67f3dceb1f7cf8d33f302d1e04`. Captures used an iPhone 17 Pro simulator (iOS 26.5) and an Android emulator (API 36.1), at their normal text sizes. Simulator review does not replace physical-device or screen-reader acceptance. + +| File | Screen | Platform | +| --- | --- | --- | +| [ios-home.png](ios-home.png) | Resident home | iPhone | +| [android-guest-pass.png](android-guest-pass.png) | Shareable guest pass | Android | +| [ios-notices.png](ios-notices.png) | Community notices | iPhone | +| [android-bills.png](android-bills.png) | Bills and payment history | Android | +| [ios-house-help.png](ios-house-help.png) | Household help | iPhone | +| [android-gate.png](android-gate.png) | Arrivals and departures | Android | + +When replacing a capture, use the native app with fictional data, keep system text at its normal size, and dismiss development overlays and keyboards unless they are the subject of the image. Preserve the full screen, check labels and safe areas, and update the capture date and revision here. Keep only the curated documentation images in this directory; local fixtures and review captures stay in `.context/`. diff --git a/docs/screenshots/android-bills.png b/docs/screenshots/android-bills.png new file mode 100644 index 0000000..6e1aa93 Binary files /dev/null and b/docs/screenshots/android-bills.png differ diff --git a/docs/screenshots/android-gate.png b/docs/screenshots/android-gate.png new file mode 100644 index 0000000..e95989e Binary files /dev/null and b/docs/screenshots/android-gate.png differ diff --git a/docs/screenshots/android-guest-pass.png b/docs/screenshots/android-guest-pass.png new file mode 100644 index 0000000..98677dc Binary files /dev/null and b/docs/screenshots/android-guest-pass.png differ diff --git a/docs/screenshots/ios-home.png b/docs/screenshots/ios-home.png new file mode 100644 index 0000000..35dea70 Binary files /dev/null and b/docs/screenshots/ios-home.png differ diff --git a/docs/screenshots/ios-house-help.png b/docs/screenshots/ios-house-help.png new file mode 100644 index 0000000..9c6048f Binary files /dev/null and b/docs/screenshots/ios-house-help.png differ diff --git a/docs/screenshots/ios-notices.png b/docs/screenshots/ios-notices.png new file mode 100644 index 0000000..118bbcc Binary files /dev/null and b/docs/screenshots/ios-notices.png differ