Pinnacle

Live Deployment (Web): https://pinnacle-web-yufy.onrender.com/
Live API (Backend): https://pinnacle-hczm.onrender.com/

Pinnacle is an advanced, AI-enhanced full-stack real estate and rental transparency platform. Built from the ground up to revolutionize how people find apartments, list properties, and connect with flatmates, Pinnacle leverages a highly dynamic, map-based interface to provide unprecedented visibility into local rental markets.

The Problem & Our Solution

The Problem

The modern rental market is fundamentally broken, characterized by opaque pricing, hidden broker fees, fragmented search experiences, and a severe lack of trustworthy localized data. Renters frequently struggle to ascertain the true market value of properties in specific localities. Is a quoted rent fair, or is it inflated? Furthermore, the process of matching a seeker's specific spatial and financial requirements with the right property owner is traditionally inefficient and fraught with friction.

The Pinnacle Solution

Pinnacle disrupts this paradigm by introducing a crowdsourced, geospatial-first approach:

1. Total Rent Transparency: By allowing the community to anonymously drop "Rent Pins" detailing exactly what they pay, Pinnacle creates a living, breathing heatmap of actual market rates.
2. Organic, Direct Connections: Enabling seamless lead generation without exposing users to spam.
3. Geospatial Intelligence: Utilizing PostGIS to handle complex spatial queries, allowing users to search within precise, customizable radii.
4. AI-Powered Valuations: Integrating Google's Gemini AI to synthesize raw market data into nuanced, actionable rent estimates and locality insights.
5. Community-Driven Moderation: Implementing a robust health scoring and reporting system to aggressively filter out spam and maintain data integrity.

---

Comprehensive Tech Stack & Architecture

Pinnacle is architected as a modern, decoupled monorepo designed for performance, scalability, and developer ergonomics.

Frontend Client (Web)

The user interface is a highly interactive Single Page Application (SPA) built for speed and responsiveness.

• Framework: Next.js 14 (React)
• Geospatial Visualization: Google Maps API (@react-google-maps/api) featuring advanced marker clustering, custom SVG markers, and interactive drawing tools.
• Styling & UI Components: Tailwind CSS for utility-first styling, paired with Shadcn UI for beautiful, accessible components (Drawers, Modals, Toasts, Badges).
• State Management: React Hooks & Context API for managing complex map state and user interactions.

Backend Service (API)

A robust, RESTful API engineered to handle complex spatial logic and secure data transactions.

• Runtime & Framework: Node.js & Express.js written entirely in strict TypeScript.
• Database Engine: PostgreSQL, chosen for its unparalleled reliability and extensibility.
• ORM (Object-Relational Mapping): Prisma Client for type-safe database access and schema management.
• Spatial Analytics: PostGIS extension. This is the heart of Pinnacle's mapping capabilities, enabling sophisticated geographic queries like ST_DWithin for radius-based searching and coordinate hashing.
• Asynchronous Job Processing: node-cron orchestrates background workers for computationally intensive tasks (like Seeker Matching) without blocking the main event loop.
• Transactional Emails: Resend API integration for secure, branded communication delivery.

Infrastructure, DevOps & Security

• Hosting: Deployed on Render using highly optimized Docker containers (node:20-alpine) for the API, ensuring environment consistency.
• Connection Pooling: Supavisor is utilized to manage database connections at scale, preventing connection exhaustion.
• Security & Rate Limiting: express-rate-limit prevents brute-force and DDoS attacks, while helmet enforces strict HTTP headers (e.g., Cross-Origin Resource Policies).

---

Deep Dive: Core Features & Workflows

1. Interactive Map-Based Exploration & Data Crowdsourcing

The interactive map is the core of the Pinnacle experience.

• Rent Pins: Community-submitted data points that display exact rent prices, BHK configurations, and community amenities (e.g., gated status). These pins act as the foundational data for all AI estimates.
• Listing Pins: Comprehensive property listings created directly by owners or verified brokers. These include rich text descriptions, availability dates, and secure contact gateways.
• Seeker Pins (Reverse Listings): A paradigm shift in apartment hunting. Renters drop a pin in their desired neighborhood, draw a search radius, specify their budget constraints and BHK preferences, and let the system work for them.

2. Intelligent Seeker Matching Engine (Automated Background Worker)

To eliminate the need for constant manual searching, Pinnacle features an automated matchmaking engine.

• The Engine (matchWorker.ts): A dedicated Node.js worker scheduled via node-cron to execute asynchronously every 6 hours.
• Spatial Querying: It leverages complex PostGIS spatial queries (ST_DWithin) to cross-reference all active SeekerPins against the database of newly added ListingPins.
• Filtering Logic: Matches are strictly filtered based on overlapping geographic boundaries (the seeker's defined radius), budget compatibility (listing rent must be ≤ seeker's max budget), and BHK requirements.
• Automated Notification: Upon identifying a match, the system securely generates a MatchLog record to prevent duplicate alerts and instantly fires a beautifully formatted, branded HTML email to the seeker via the Resend API, notifying them of the new property in their desired area.

3. Secure, Anti-Spam Contact Request Flow

Privacy is paramount. Pinnacle ensures that property owners are not subjected to spam or unwanted solicitations.

• The Mechanism: Raw email addresses and phone numbers are never publicly exposed on the map interface.
• The Workflow: When a seeker identifies an appealing listing, they initiate contact via an "I'm interested" action. The backend /api/contact/request endpoint intercepts this request.
• Email Injection: The system dynamically injects the seeker's validated contact details into a secure HTML email template.
• Dispatch: This sanitized request is dispatched directly to the listing owner's inbox using the Resend API, creating a frictionless, secure lead generation pipeline.

4. Robust Health Scores & Trust Badges

To maintain a high-signal, low-noise environment, Pinnacle relies on community moderation backed by algorithmic enforcement.

• Reporting System: Users can flag inaccurate, outdated, or fraudulent pins. The backend meticulously tracks the reportCount and the reporter's ipHash to mitigate malicious reporting bursts.
• Algorithmic Hiding: If a pin crosses a predefined threshold of unique reports, it is automatically flagged and hidden from the public map (isHidden: true).
• Visual Trust Indicators: The UI (specifically HealthBadge.tsx and the PinDrawer components) dynamically renders trust badges (e.g., "Verified / High Trust", "Moderate Trust", "Low Trust") based on a complex calculation of the pin's active report count, total upvotes, and overall engagement metrics.

5. AI-Powered Rent Estimator

Pinnacle doesn't just show data; it interprets it.

• Integration: Deep integration with the Google Gemini API.
• Contextual Analysis: When a user requests an estimate for a specific locality, the backend aggregates nearby crowdsourced Rent Pins and feeds this localized dataset, along with the user's specific requirements, into the LLM.
• The Output: The AI generates a highly nuanced, localized fair rent estimate, factoring in market trends and providing qualitative insights that raw numbers alone cannot convey.

6. Watchlists & Granular Ratings

• Dynamic Watchlists: Users can monitor specific geographic areas and configurations. Changes in the market or new listings trigger updates.
• Locality Ratings: Beyond simple rent prices, users can rate specific localities and building qualities, adding a crucial layer of qualitative data to the platform's quantitative base.

---

Database Schema Overview (Prisma)

The database is heavily optimized for geospatial operations and relational integrity. Key models include:

• RentPin: Crowdsourced rent data (location, rent, bhk, reportCount, upvotes).
• ListingPin: Owner properties (location, rent, contactEmail, imageUrls, isActive).
• SeekerPin: Renter requirements (location, radiusKm, minBudget, maxBudget).
• MatchLog: Tracks successful spatial matches between Seekers and Listings to manage notification states (PENDING, SENT, FAILED).
• Rating & Watchlist: User engagement and market tracking models.

---

Comprehensive Local Development Guide

Prerequisites

Ensure your development environment meets the following requirements:

• Node.js: v20 LTS (Recommended for maximum compatibility).
• Database: PostgreSQL database with the PostGIS extension enabled (Supabase is recommended for easy PostGIS setup).
• API Keys Required:
  • Google Maps API Key (with Maps JavaScript API and Places API enabled).
  • Resend API Key (for email functionality).
  • Google Gemini API Key (for the AI Estimator).

1. Repository Initialization

```bash git clone https://github.com/yourusername/Pinnacle.git cd Pinnacle

Install Frontend dependencies

cd web npm install

Install Backend dependencies

cd ../api npm install ```

2. Environment Configuration

Duplicate the provided .env.example file in the root directory and rename it to .env. Carefully populate it with your specific API keys and database connection strings. Ensure your DATABASE_URL includes the necessary pooling parameters if using Supavisor.

3. Database Migration & Seeding (API)

Initialize your database schema: ```bash cd api

Push the Prisma schema directly to the database to create all required tables and enums

npx prisma db push --accept-data-loss

Generate the Prisma Client tailored to your database engine

npm run prisma:generate ```

4. Launching the Application

The application requires both the frontend and backend to be running concurrently.

Terminal 1: Start the Backend Service ```bash cd api npm run dev ``` The API will boot up and bind to http://localhost:4000/api. You will see confirmation logs for the cron job initialization.

Terminal 2: Start the Frontend Client ```bash cd web npm run dev ``` The frontend will compile and be accessible at http://localhost:3000.

---

Security Posture

• No Exfiltration: All sensitive .env files are strictly excluded via .gitignore.
• Validation First: Every API endpoint utilizes strict schema validation (via Zod or custom middleware) to sanitize inputs before database interaction.
• Graceful Shutdowns: The Node.js server implements robust SIGTERM handlers to ensure database connections are closed cleanly during deployments or container restarts.