How philly-truce/phillytruce_2025 works
Project Type & Purpose
• This is a full-stack, Next.js-based web application (“Philly Truce”) that provides an incident-management platform. Users (students, community members, mediators) interact via a React/Tailwind front-end; authentication is handled by Next Auth; business logic and data persistence live in Next.js API routes backed by Prisma ORM and MongoDB; Twilio is used for OTP and messaging.
File-Structure Anatomy
• src/app – React pages and layouts (TSX), Next.js routing
• src/app/api – Next.js API routes (route.ts) implementing REST endpoints (auth, create-report, messaging, conversation management, etc.)
• src/lib – shared utilities (Twilio client, provider, general helpers)
• src/db – MongoDB connection and Prisma schema mappings
• src/components – reusable React UI components (auth, create-report, messages, UI primitives)
• server – an optional Express microservice (server/app.ts) for inbound-message webhooks or custom endpoints
• public – static assets, PWA manifest, service worker
• dist – compiled Next.js output
Key Architectural Patterns
• Layered architecture:
• Presentation Layer (React pages + components)
• API Layer (Next.js route handlers, optional Express server)
• Domain/Service Layer (business rules in lib/utils, Twilio wrappers)
• Data Layer (Prisma ORM → MongoDB)
• Authentication via Next Auth (uses API routes + database sessions)
• External integration: Twilio SMS/OTP for auth and messaging
• MVC-style separation: pages = views, API routes = controllers, Prisma models = data
Main Components & Interactions
• Browser Client
• Sends page requests to Next.js server (SSR/SSG)
• Calls Next.js API endpoints via fetch/Axios
• Renders React components styled by Tailwind + Shadcn UI
• Next.js Server
• Serves HTML/JS bundles for pages (src/app)
• Hosts API routes (src/app/api/*.ts)
• Integrates Next Auth middleware (src/app/middleware.ts)
• Express Microservice (optional)
• server/app.ts handles Twilio webhooks or legacy endpoints
• Domain Services
• Twilio-Client (src/lib/twilio-client.ts) wraps SMS/OTP calls
• Utility functions (src/lib/utils.ts)
• ORM & Database
• Prisma client (db/prisma/index.ts)
• MongoDB schemas (db/mongoDB/*.ts)
• External Services
• Twilio REST API for SMS/OTP/inbound messages