Monorep

.github/workflows/ci.yml

@@ -7,8 +7,8 @@ on:
     branches: [main]
 
 jobs:
-  backend:
-    name: Backend (API)
+  api:
+    name: API
     runs-on: ubuntu-latest
     defaults:
       run:
@@ -45,3 +45,37 @@ jobs:
 
       - name: Build
         run: pnpm --filter sidewalk-api build
+
+  web:
+    name: Web
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: .
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Lint
+        run: pnpm --filter sidewalk-web lint
+
+      - name: Type check
+        run: pnpm --filter sidewalk-web typecheck
+
+      - name: Build
+        run: pnpm --filter sidewalk-web build

.gitignore

@@ -23,6 +23,7 @@ lerna-debug.log*
 dist/
 build/
 out/
+.next/
 coverage/
 *.tsbuildinfo
 

README.md

@@ -2,222 +2,125 @@
 
 [![CI](https://github.com/MixMatch-Inc/Sidewalk/actions/workflows/ci.yml/badge.svg)](https://github.com/MixMatch-Inc/Sidewalk/actions/workflows/ci.yml)
 
-**Sidewalk** is an open-source, civic reporting and accountability platform that empowers citizens to document local issues, track government response, and ensure follow-through—publicly and transparently.
+Sidewalk is a civic reporting monorepo. It currently contains:
 
-Citizens can report problems like damaged roads, broken streetlights, flooding, waste issues, or public safety concerns, attach media and location data, and monitor progress from *reported* to *resolved*.
+- `apps/api`: Express API for auth, reports, media uploads, health checks, and background jobs
+- `apps/web`: Next.js web app shell for diagnostics and future citizen/admin workflows
+- `apps/mobile`: Expo React Native app
+- `packages/stellar`: shared Stellar integration package
 
-What sets Sidewalk apart is its **Stellar-powered accountability layer**. By anchoring civic actions on-chain, Sidewalk turns public complaints into verifiable records that cannot be ignored, altered, or quietly deleted.
+The repository uses `pnpm` workspaces as the source of truth. Use `pnpm`, not `npm`, for install and workspace tasks.
 
-> **If it’s on-chain, it can’t be swept under the rug.**
-
-[SIDEWALK FIGMA](https://www.figma.com/design/cH6GFhWhtgxzESR8pedNGl/Sidewalk?node-id=0-1&t=n3OH48FSO4NjbBf3-1)
-
----
-
-## 🌍 Why Sidewalk?
-
-Civic reporting tools already exist—but trust, incentives, and accountability are often missing.
-
-Most platforms are:
-* Centralized and opaque
-* Easy to manipulate or abandon
-* Focused on reporting, not resolution
-
-Sidewalk is built around a different idea:
-**Civic participation should be verifiable, incentivized, and impossible to ignore.**
-
-By combining community reporting with blockchain-backed transparency, Sidewalk transforms everyday civic complaints into durable public records and measurable performance data.
-
----
-
-## ✨ Core Capabilities
-
-* **Civic Issue Reporting** – Report infrastructure and public service problems
-* **Media & Location Proof** – Photos, videos, timestamps, and geotags
-* **Status Tracking** – Follow issues from report → acknowledgement → resolution
-* **Public Metrics** – Resolution time and responsiveness are visible to all
-* **Mobile-First Design** – Built for fast, on-the-ground reporting
-
----
-
-## ⭐ The Stellar Advantage
-
-Sidewalk uses **Stellar** as a trust and coordination layer—not as hype, but as infrastructure.
-
-### 1. Proof & Transparency
-Every critical civic action is anchored on-chain:
-* Issue creation
-* Official acknowledgement
-* Resolution confirmation
-* Time-to-fix metrics
-
-Each report is associated with a **Stellar transaction hash**, providing immutable, timestamped proof. This ensures that complaints cannot be edited, hidden, or erased after submission.
-
-### 2. Tokenized Civic Accountability
-Sidewalk introduces a **community civic token** on Stellar. Citizens earn tokens for submitting valid reports and verifying others. Tokens can be used to vote on priority issues or access local civic perks.
-
-### 3. Smart Escalation & Deadlines
-Sidewalk enforces accountability through time-bound logic. Missed deadlines trigger automatic escalation, and unresolved issues surface on a public **Hall of Accountability**.
-
----
-
-## 🧱 Architecture Overview
-
-Sidewalk is built as a scalable **Monorepo** using `pnpm` workspaces, with a clear separation between the API, mobile experience, and shared services.
-
-| Layer | Technology |
-| :--- | :--- |
-| **Frontend** | React Native (Expo) |
-| **Backend API** | Node.js / Express (Modular Monolith) |
-| **Database** | MongoDB |
-| **Blockchain** | **Stellar** (via `@sidewalk/stellar` package) |
-| **Tooling** | `pnpm`, TypeScript, `tsx` |
-
----
-
-## 📦 Monorepo Structure
+## Workspace layout
 
 ```text
 sidewalk/
 ├── apps/
-│   ├── api/              # Express backend (Modular Monolith)
-│   └── mobile/           # React Native App (Expo)
-│
+│   ├── api/
+│   ├── mobile/
+│   └── web/
 ├── packages/
-│   └── stellar/          # Shared Stellar Service & SDK
-│
-├── config/               # Shared configurations
-├── package.json          # Root workspace config
-└── pnpm-workspace.yaml   # Workspace definitions
-
+│   └── stellar/
+├── package.json
+├── pnpm-workspace.yaml
+└── tsconfig.base.json
 ```
 
----
-
-## 🚀 Getting Started
-
-Follow these steps to get the development environment running.
-
-### 1. Prerequisites
-
-* **Node.js** (v18 or higher)
-* **pnpm** (Install via `npm install -g pnpm`)
-* **MongoDB** (Running locally or via Atlas)
-* **Expo Go** app on your phone (optional, for physical device testing)
+## Prerequisites
 
-### 2. Installation
+- Node.js 20 or later
+- pnpm 9
+- MongoDB for the API
+- Redis for BullMQ-backed workers
+- Stellar testnet account secret for anchoring flows
+- Expo Go or emulator tooling for mobile work
 
-Clone the repo and install dependencies using `pnpm`.
+## Bootstrap
 
 ```bash
-git clone [https://github.com/your-org/sidewalk.git](https://github.com/your-org/sidewalk.git)
-cd sidewalk
-
-# Install all dependencies for all packages
 pnpm install
-
-```
-
-### 3. Build Shared Packages
-
-Before running the apps, you must build the shared `@sidewalk/stellar` package so the API can consume it.
-
-```bash
-# Build all packages
-pnpm -r build
-
 ```
 
-### 4. Configure Environment
-
-Set up the environment variables for the API.
+Root workspace scripts:
 
-```bash
-# Create the .env file in the API folder
-cp apps/api/.env.example apps/api/.env
+- `pnpm dev:api`
+- `pnpm dev:web`
+- `pnpm dev:mobile`
+- `pnpm build`
+- `pnpm lint`
+- `pnpm typecheck`
+- `pnpm check`
 
-# Update apps/api/.env with your MongoDB URI (defaults to local)
-# MONGO_URI=mongodb://localhost:27017/sidewalk
+## Environment setup
 
-```
+Current runtime requirements come primarily from the API and workers:
 
----
+- `MONGO_URI`
+- `JWT_SECRET`
+- `STELLAR_SECRET_KEY`
+- `REDIS_URL` for queue-backed media processing and Stellar anchoring
+- S3 variables required by the media module
+- `RESEND_API_KEY` if OTP email delivery should send real emails
 
-## 🏃‍♂️ Running the Project
+If Redis or Resend are missing, some flows already degrade safely:
 
-You will typically run the Backend and the Mobile App in two separate terminal tabs.
+- media queue falls back to storing originals without worker processing
+- Stellar anchor queue stays unavailable without crashing the API
+- OTP email delivery logs codes instead of sending them
 
-### Terminal 1: Backend API
+## Running the apps
 
-This starts the Express server in watch mode.
+Backend API:
 
 ```bash
-# Run from the root directory
-npm run dev:api
-
+pnpm dev:api
 ```
 
-*You should see: `🚀 Server running on port 5000` and `✨ Stellar Service initialized`.*
-
-### Terminal 2: Mobile App
-
-This starts the Expo development server.
+Web app:
 
 ```bash
-cd apps/mobile
-npx expo start
-
+pnpm dev:web
 ```
 
-* Press `a` to run on **Android Emulator**.
-* Press `i` to run on **iOS Simulator**.
-* Scan the QR code to run on your physical device.
-
----
-
-## ✅ Local Quality Checks
-
-Before submitting a PR, run these checks locally to ensure CI will pass:
+Mobile app:
 
 ```bash
-# Install dependencies
-pnpm install
-
-# Run all checks for a specific package
-pnpm --filter sidewalk-api lint && pnpm --filter sidewalk-api typecheck && pnpm --filter sidewalk-api build
-pnpm --filter mobile lint && pnpm --filter mobile typecheck
-pnpm --filter @sidewalk/stellar lint && pnpm --filter @sidewalk/stellar typecheck && pnpm --filter @sidewalk/stellar build
-
-# Or run checks individually
-pnpm --filter <package-name> lint       # Run ESLint
-pnpm --filter <package-name> typecheck  # Run TypeScript type checking
-pnpm --filter <package-name> build      # Build the package
+pnpm dev:mobile
 ```
 
----
+## Local quality checks
 
-## 🤝 Contributing
+Run the full workspace checks:
 
-Sidewalk is open-source and built for contributors who care about civic tech, transparency, and real-world impact.
+```bash
+pnpm check
+```
 
-1. Fork the repository
-2. Create a branch from `main`
-3. Pick an issue or propose one
-4. Open a PR with context and screenshots
-5. Ensure CI checks pass before requesting review
+Or run package-specific checks:
 
----
+```bash
+pnpm --filter sidewalk-api lint
+pnpm --filter sidewalk-api typecheck
+pnpm --filter sidewalk-api build
 
-## 💬 Community & Support
+pnpm --filter sidewalk-web lint
+pnpm --filter sidewalk-web typecheck
+pnpm --filter sidewalk-web build
 
-👉 Telegram: [https://t.me/+gRA3CdyekZw3MWM0](https://t.me/+gRA3CdyekZw3MWM0)
+pnpm --filter mobile lint
+pnpm --filter mobile typecheck
 
----
+pnpm --filter @sidewalk/stellar lint
+pnpm --filter @sidewalk/stellar typecheck
+pnpm --filter @sidewalk/stellar build
+```
 
-## 📄 License
+## Notes for contributors
 
-MIT License
+- Each app/package should remain independently buildable from `main`
+- Shared logic belongs in `packages/*` only when it is stable enough for cross-app reuse
+- Prefer additive changes that do not assume other branches have been merged
 
-```
+## License
 
-```
+MIT

apps/web/eslint.config.mjs

@@ -1,3 +1,17 @@
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { FlatCompat } from "@eslint/eslintrc";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const compat = new FlatCompat({
+  baseDirectory: __dirname,
+});
+
+const config = [...compat.extends("next/core-web-vitals", "next/typescript")];
+
+export default config;
 import js from "@eslint/js";
 import tseslint from "typescript-eslint";