# philly-truce/phillytruce_2025 architecture

> Architecture diagram of the GitHub repository philly-truce/phillytruce_2025, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/philly-truce/phillytruce_2025
- Repository: https://github.com/philly-truce/phillytruce_2025

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Zone
    subgraph "Frontend Layer" 
        direction TB
        Browser["Browser Client"]:::frontend
        ReactUI["React UI<br/>(src/app)"]:::frontend
        UIComponents["Reusable UI Components<br/>(src/components)"]:::frontend
    end

    %% Backend Zone
    subgraph "Backend Layer" 
        direction TB
        NextServer["Next.js Server<br/>(TS, Tailwind, Shadcn)"]:::backend
        Middleware["Next Auth Middleware<br/>(src/app/middleware.ts)"]:::backend
        subgraph "API Layer" 
            direction TB
            NextAPI["Next.js API Routes<br/>(src/app/api)"]:::backend
            AuthAPI["Auth API Routes"]:::backend
            ReportAPI["Reporting API"]:::backend
            MessageAPI["Messaging API"]:::backend
        end
        subgraph "Express Microservice" 
            direction TB
            ExpressApp["Express App<br/>(server/app.ts)"]:::backend
            ExpressModel["User Model<br/>(server/model/userSchema.ts)"]:::backend
            ExpressRouter["Auth/Webhook Router<br/>(server/router/auth.js)"]:::backend
        end
    end

    %% Service Layer
    subgraph "Domain Services" 
        direction TB
        TwilioClient["Twilio Client Wrapper<br/>(src/lib/twilio-client.ts)"]:::service
        TwilioProvider["Twilio Provider<br/>(src/lib/twilio-provider.tsx)"]:::service
        Utils["General Utilities<br/>(src/lib/utils.ts)"]:::service
    end

    %% Data Layer
    subgraph "Data Layer" 
        direction TB
        PrismaClient["Prisma Client<br/>(dist/db/prisma/index.js)"]:::data
        subgraph "MongoDB Schemas" 
            direction TB
            DBConnect["DB Connection<br/>(src/db/mongoDB/db-connect.ts)"]:::data
            UserSchema["User Schema<br/>(src/db/mongoDB/user-schema.ts)"]:::data
            ReportSchema["Report Schema<br/>(src/db/mongoDB/report-schema.ts)"]:::data
            WitnessSchema["Witness Schema<br/>(src/db/mongoDB/witness-schema.ts)"]:::data
        end
    end

    %% External Services
    subgraph "External Services" 
        direction TB
        TwilioAPI["Twilio SMS/OTP API"]:::external
    end

    %% Connections
    Browser -->|"SSR/CSR Requests"| ReactUI
    ReactUI -->|"Uses Components"| UIComponents
    ReactUI -->|"Fetch/Axios"| NextAPI
    Browser -->|"Auth Calls"| AuthAPI

    NextServer -->|Serves Pages| ReactUI
    NextServer -->|Hosts API| NextAPI
    NextAPI -->|Uses Middleware| Middleware

    NextAPI -->|"POST /auth/*"| AuthAPI
    NextAPI -->|"POST /api/create-report"| ReportAPI
    NextAPI -->|"POST /api/messaging"| MessageAPI

    AuthAPI -->|"Session CRUD"| PrismaClient
    ReportAPI -->|"Prisma.create, findMany"| PrismaClient
    MessageAPI -->|"Prisma operations"| PrismaClient

    NextAPI -->|"Calls Twilio"| TwilioClient
    TwilioClient -->|"SMS/OTP"| TwilioAPI
    NextAPI -->|"Uses Utils"| Utils

    ExpressApp -->|"Receives Webhooks"| TwilioAPI
    ExpressApp -->|"Routes to Next.js API"| NextAPI

    PrismaClient -->|"Connects to"| DBConnect
    DBConnect -->|"Applies Schemas"| UserSchema
    DBConnect -->|"Applies Schemas"| ReportSchema
    DBConnect -->|"Applies Schemas"| WitnessSchema

    %% Click Events
    click ReactUI "https://github.com/philly-truce/phillytruce_2025/tree/main/src/app"
    click UIComponents "https://github.com/philly-truce/phillytruce_2025/tree/main/src/components"
    click NextAPI "https://github.com/philly-truce/phillytruce_2025/tree/main/src/app/api"
    click Middleware "https://github.com/philly-truce/phillytruce_2025/blob/main/src/app/middleware.ts"
    click AuthAPI "https://github.com/philly-truce/phillytruce_2025/blob/main/src/app/api/auth/[...nextauth].ts"
    click AuthAPI "https://github.com/philly-truce/phillytruce_2025/blob/main/src/app/api/auth/check-verification.ts"
    click AuthAPI "https://github.com/philly-truce/phillytruce_2025/blob/main/src/app/api/auth/send-verification.ts"
    click AuthAPI "https://github.com/philly-truce/phillytruce_2025/blob/main/src/app/api/auth/sign-up/route.ts"
    click TwilioClient "https://github.com/philly-truce/phillytruce_2025/blob/main/src/lib/twilio-client.ts"
    click TwilioProvider "https://github.com/philly-truce/phillytruce_2025/blob/main/src/lib/twilio-provider.tsx"
    click Utils "https://github.com/philly-truce/phillytruce_2025/blob/main/src/lib/utils.ts"
    click DBConnect "https://github.com/philly-truce/phillytruce_2025/blob/main/src/db/mongoDB/db-connect.ts"
    click UserSchema "https://github.com/philly-truce/phillytruce_2025/blob/main/src/db/mongoDB/user-schema.ts"
    click ReportSchema "https://github.com/philly-truce/phillytruce_2025/blob/main/src/db/mongoDB/report-schema.ts"
    click WitnessSchema "https://github.com/philly-truce/phillytruce_2025/blob/main/src/db/mongoDB/witness-schema.ts"
    click PrismaClient "https://github.com/philly-truce/phillytruce_2025/blob/main/dist/db/prisma/index.js"
    click ExpressApp "https://github.com/philly-truce/phillytruce_2025/blob/main/server/app.ts"
    click ExpressModel "https://github.com/philly-truce/phillytruce_2025/blob/main/server/model/userSchema.ts"
    click ExpressRouter "https://github.com/philly-truce/phillytruce_2025/blob/main/server/router/auth.js"
    click TwilioAPI "https://github.com/philly-truce/phillytruce_2025/tree/main/N/A"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef backend fill:#DFF7DF,stroke:#34A853,stroke-width:1px
    classDef service fill:#FFF4CC,stroke:#FBBC05,stroke-width:1px
    classDef data fill:#FFEFE0,stroke:#EA4335,stroke-width:1px
    classDef external fill:#FCE8F3,stroke:#D147A3,stroke-width:1px
```
