Kindly — Sustainable Acts of Kindness Platform

Kindly is a high-performance, community-centered web application designed to accelerate localized environmental engagement and sustainability initiatives. The platform bridges the gap between grassroots volunteer actions and strategic environmental oversight by enabling users to report ecological hotspots, coordinate community cleanup events, access an educational hub, and monitor region-wide impact indicators through data aggregation panels.

Developed as a validated Minimum Viable Product (MVP) within a strict 6-week fixed lifecycle and $12,000 budget ceiling, Kindly combines a predictive planning architecture with adaptive, AI-assisted development sprint workflows.

---

🚀 Key Functional Modules

The platform delivers specialized user-interface layouts tailored around three main roles:

1. Community Volunteer Hub

• Account Provisioning: Secure, encrypted onboarding pipelines using identity hashing and session token states.
• Geospatial Incident Reporting: Interactive map-based interface to mark environmental concerns (such as illegal dump sites, infrastructure neglect, or micro-pollution events) with exact coordinate attributes.
• Activity & Engagement Ledgers: Dynamic profile scorecards tracking individual volunteer activity history, clean-up enrollment logs, and historical participation metrics.

2. Event Organizer Core

• Event Creation Pipelines: Structured, multi-field data entry forms to publish local community cleanups, tree-planting projects, recycling drives, and environmental workshops.
• Visual Asset Enforcements: Automated asset validation hooks that pair event categories with optimized design assets, maintaining visual consistency across light and dark user interface states.
• Resource Mapping Matrices: Backlog tracking tools to allocate specific material lists and task responsibilities directly within event profiles.

3. Report Analyst Dashboard

• Data Aggregation Engine: Client-side data compilation routines that transform raw transactional database entries into region-wide sustainability indicators.
• Impact Visualizations: Live analytics interfaces tracking total reported incidents, resolved environmental alerts, active field projects, and cumulative community contribution numbers.

---

🛠 Tech Stack & Architecture

Kindly leverages a decoupled, type-safe architecture optimized for fast load times, rigid data validation, and responsive mobile rendering.

┌──────────────────────────────────────────────────────────────┐
│                 FRONTEND APPLICATION LAYER                    │
│  React 19 • TypeScript • TanStack Start • Tailwind CSS        │
└───────────────────────────────┬───────────────────────────────┘
                                │
                HTTPS / WebSockets • API Integration Layer
                                ▼
┌──────────────────────────────────────────────────────────────┐
│                 BACKEND INFRASTRUCTURE LAYER                 │
│                Supabase BaaS (PostgreSQL Engine)             │
├──────────────────────────────────────────────────────────────┤
│ • Supabase Auth Engine      • Row-Level Security (RLS)        │
│ • OpenStreetMap / Leaflet   • Cloud Object Storage            │
└──────────────────────────────────────────────────────────────┘

🔒 API Integrations & Database Security

External Service Connectors

1. Supabase Auth API: Protects system routes through encrypted password authentication and JSON Web Token (JWT) session persistence rules.
2. OpenStreetMap / Leaflet Map API: Renders low-latency geospatial coordinate tiles on client browsers, processing real-time dataset requests to place dynamic, category-specific marker pins on map canvases.

Database Constraint and Row-Level Security (RLS) Engineering

Data validation policies and access limits are enforced natively at the database layer using explicit PostgreSQL RLS script blocks:

-- Enable Row-Level Security Mappings ALTER TABLE public.profiles ENABLE ROW LEVEL SECURITY; ALTER TABLE public.reports ENABLE ROW LEVEL SECURITY; ALTER TABLE public.events ENABLE ROW LEVEL SECURITY;

-- Public Profile View Constraints CREATE POLICY "Allow public read access to active profile records" ON public.profiles FOR SELECT USING (true);

CREATE POLICY "Allow authenticated owners to modify their profile data records" ON public.profiles FOR UPDATE USING (auth.uid() = id);

-- Environmental Incident Logging Controls CREATE POLICY "Allow open visibility of logged environmental reports" ON public.reports FOR SELECT USING (true);

┌──────────────────────────────────────────────────────────────┐
│     SECURITY & ACCESS CONTROL — ROW‑LEVEL SECURITY (RLS)      │
├──────────────────────────────────────────────────────────────┤
│  CREATE POLICY "Allow authenticated volunteers to generate    │
│  new environmental reports"                                   │
│  ON public.reports FOR INSERT                                 │
│  WITH CHECK (auth.role() = 'authenticated');                  │
└──────────────────────────────────────────────────────────────┘


┌──────────────────────────────────────────────────────────────┐
│                PROJECT DIRECTORY STRUCTURE                    │
│                     kindly-platform/                          │
├──────────────────────────────────────────────────────────────┤
│ .vite/                         — Build & optimization cache   │
│ src/                           — Application source root      │
│   components/                  — Reusable UI + design system  │
│     ui/                        — Atomic UI primitives          │
│     Map.tsx                    — Leaflet OSM rendering canvas │
│     EventCard.tsx              — Event display module          │
│     ReportForm.tsx             — Environmental report form     │
│   integrity/                   — Security rules & validators   │
│   layouts/                     — Page wrappers & theme logic   │
│   lib/                         — Supabase client init          │
│   pages/                       — Route‑level views             │
│     Auth.tsx                   — Identity gate                 │
│     Dashboard.tsx              — Metrics dashboard             │
│     Index.tsx                  — Main map + navigation hub     │
│     Profile.tsx                — Volunteer history             │
│   App.tsx                      — Routing + layout engine       │
│   index.css                    — Global styles & tokens        │
│   main.tsx                     — App bootstrap entry           │
│ supabase/                      — Database environment          │
│   migrations/                  — PostgreSQL schema scripts     │
│ index.html                     — Root DOM mount point          │
│ package.json                   — Dependencies & scripts        │
│ vite.config.ts                 — Vite build configuration      │
└──────────────────────────────────────────────────────────────┘

📦 Local Installation & Setup

InstructionsEnsure your local development environment has Node.js (v18.x or higher) and NPM initialized.

1. Clone and Extract DependenciesBashgit clone https://github.com/team-1-cs632/kindly-platform.git cd kindly-platform npm install
2. Configure Environment Boundary VariablesCreate an absolute system reference file named .env in the root of your project workspace directory:Code snippetVITE_SUPABASE_URL=https://your-configured-supabase-instance.supabase.co VITE_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.your-secure-anonymous-public-key-token
3. Run the Local Development ContextBashnpm run dev The application compiler engine will initialize a local web host instance at http://localhost:5173.4.

Compile Production DeploymentsBashnpm run build The build process compiles, optimizes, and outputs minified static deployment configurations directly to the /dist directory.