Docs

CollegeLogistics — Platform Overview & Capabilities

Document version: April 2026
Audience: Technical readers new to the codebase with software product experience
Stack: React 18, Tailwind CSS, Base44 BaaS (Deno backend functions), TanStack Query

1. What CollegeLogistics Is

CollegeLogistics is a campus-aware logistics marketplace built specifically for college students and their families navigating the complexity of move-in season. The platform acts as the connective tissue between a family's immediate practical needs — finding movers, storage units, shipping services, airport transfers, hotels near campus — and the policy constraints each individual university enforces (what items are prohibited in dorms, what services the school officially endorses, what dates move-in windows open).

The core problem CollegeLogistics solves is fragmentation. Today, a family moving a freshman into a dorm must separately check the school's housing policy PDF, cross-reference prohibited items, find movers that serve that specific city, book hotels, coordinate airport pickup, and arrange storage — all without any tool that ties these concerns together. CollegeLogistics positions itself as the "Kayak of college move-in": a single destination where the school's policy context is surfaced alongside curated service offers, affiliate links, and bookable provider services — all filtered to the student's specific campus.

The business model is multi-sided. On the consumer side the app is free. Revenue comes from affiliate commissions, formal partner agreements with logistics providers, and an optional human Concierge service tier.

2. How the Platform Works — End-to-End Flow

2.1 Public Browse Experience (No Login Required)

The app is publicly accessible. All pages behind the main navigation render without authentication. Anonymous visitors get a session via AppSession, page views via AppPageView, and events via AppEvent.

Key public pages:

Home (/) — hero, service category tiles, journey guide tiles, campus policy teaser
Travel, Storage, Shipping, MoveIn — per-category service landing pages
DormPolicies / CampusGuide — public-facing policy explorer
Blog (/Blog) — SEO content, publicly indexed
Offers (/Offers) — affiliate offer marketplace, filterable by campus and category
Concierge (/Concierge) — high-touch intake, no login required

2.2 Authentication Gate

Authentication is hybrid: the platform is deliberately open, but certain features trigger a soft gate. The useAuthGate hook determines whether to show a SignInBanner based on visit patterns. A hard login redirect only fires for explicitly protected routes.

2.3 Campus Selection and Context

Campus selection is the most important UX primitive in the platform. It contextualizes everything: policy lookup, provider filtering, offer scoping, and travel planning.

CampusContextBanner lets users pick or change their campus
Selected campus is stored in localStorage via selectedCollegeStore and synced to UserProfile.campus_pref when authenticated
The College entity is the canonical campus record

2.4 Dorm Policy Discovery — Ingestion Pipeline

Source (PDF / URL / pasted text)
  └─→ DormPolicyImportJob (created by admin)
        └─→ runImportJob.js (orchestrator)
              └─→ extractDormPoliciesFromDocument.js (AI extraction)
                    └─→ DormPolicyImportRow records (one per extracted policy item)
                          └─→ publishDormPolicyImportJob.js
                                └─→ CollegeDormPolicy records (published, live)

2.5 Marketplace Browsing, Filtering, and Service Booking

Service Booking Flow:

User browses Provider cards on category pages
ProviderCard → ProviderDetailModal → booking form
MultiStepBookingModal collects date, address, notes, contact info
On submit: creates a ServiceBooking record (status: 'pending')
sendBookingConfirmation backend function sends a confirmation email
awardBookingRewards backend function creates a RewardsLedger entry

2.6 My Stuff Dashboard (`/MyStuff`)

After login, authenticated users access a personal dashboard with bookings, receipts, reminders, documents, favorites, rewards, and travel plans.

3. Core Capabilities

3.1 Campus Policy Intelligence Engine

Ingests raw university housing documents and produces structured, queryable policy records. Supports three source modes: PDF, URL, and pasted text.

3.2 Logistics Marketplace

Surfaces providers across eight categories: Stays, Travel, Activities, Moving, Storage, Shipping, Retail, Services.

3.3 Service Booking System

The ServiceBooking entity is the transactional core. Lifecycle: pending → confirmed → in_progress → completed → cancelled.

3.4 Dorm Policy Search

Operates at the item level via DormPolicyItem records. Status vocabulary: college_provided, school_endorsed, not_listed, prohibited, unknown.

3.5 AI Campus Intelligence

CampusIntelligence records hold AI-generated summaries per campus. The ClaudeChatWidget and chatWithClaude backend function power a context-aware chat assistant using Claude 3.5 Sonnet.

3.6 Rewards Engine

The RewardsLedger is a double-entry append-only ledger of point transactions. Point values: 75 points for service bookings, 50 for visit bookings.

3.7 Offer & Affiliate System

Offers are promotional listings scoped to a campus or nationwide. The postback backend function handles inbound postback notifications from affiliate networks.

3.8 Journey Guides

Journey records are guided logical paths through the marketplace. They appear as tiled cards on the Home page and Welcome modal.

3.9 Blog & Content System

The BlogPost entity powers a full SEO content system with WYSIWYG authoring via react-quill.

3.10 Concierge Services

The ConciergeRequest entity captures high-touch intake submissions. A Twilio phone integration provides a concierge phone number.

3.11 Analytics Engine

CollegeLogistics runs a fully first-party analytics stack. The useFirstPartyAnalytics hook fires on page load to write AppSession, AppPageView, and AppVisitor records.

3.12 Provider Portal

Providers with role: 'provider' access a dashboard showing their ServiceBooking queue, service catalog, analytics, and calendar.

4. Data Model Summary

| Entity | Purpose | |---|---| | College | Canonical campus record | | CollegeDormPolicy | Published structured policy rows | | DormPolicyItem | Item-level dorm policy catalog | | Provider | Service provider directory entry | | Service | Bookable service SKU | | ServiceBooking | Transactional booking record | | Offer | Promotional listing | | Affiliate | Affiliate partner configuration | | Click | Affiliate click tracking | | Conversion | Affiliate conversion postback | | CampusIntelligence | AI-generated campus summary | | CampusGuide | Markdown move-in guide per campus | | Journey | Guided logistics path configuration | | RewardsLedger | Points transaction log | | BlogPost | SEO content article | | ConciergeRequest | High-touch concierge intake | | DormPolicyImportJob | Import pipeline job tracker |

5. Integration & Automation Touchpoints

5.1 AI / Claude Integration

| Function | Model | Purpose | |---|---|---| | AI chat assistant (chatWithClaude.js) | claude-3-5-sonnet-20241022 | Powers the ClaudeChatWidget | | Dorm policy extraction | InvokeLLM | Extracts structured policy rows | | Campus content generation | InvokeLLM with internet | Auto-generates CampusIntelligence summaries |

5.2 Email System

All transactional email is sent via the platform email integration (called from backend functions). Covers booking confirmations, reminders, checklist downloads, and concierge voicemail alerts.

Twilio: Inbound calls and voicemails handled by twilioInboundCall.js and twilioVoicemailReceived.js. Required secrets: TWILIO_AUTH_TOKEN, ACCOUNT_SID.

5.3 Scheduled / Background Functions

| Function | Purpose | |---|---| | rebuildAnalyticsDaily | Roll up clicks/conversions | | nightlyVirtualTourMaintenance | Check virtual tour URL health | | sendBookingReminders | Send 24h-before reminders | | expireInactiveOffers | Set expired offers to inactive | | recomputeCuratedColleges | Recompute curated/launch-ready flags |

CollegeLogistics — Admin Guide

Document version: April 2026
Audience: Platform Admins (role = admin) and University Admins
Access: Platform Admin → /Admin | University Admin → /UAdmin

1. Admin Roles & Permissions Matrix

| Role | Value in DB | Entry Point | Scope | |---|---|---|---| | Platform Admin | admin | /Admin | Full system access | | University Admin | via UniversityAdmin entity | /UAdmin | Scoped to assigned college(s) only |

Note: University Admins are NOT stored as role = 'university_admin'. They are identified by having an active UniversityAdmin record linking their email to a college_id.

Permissions Matrix

| Capability | Platform Admin | University Admin | |---|---|---| | View / edit all colleges | Full | None | | Manage dorm policies | Full | Read-only (scoped) | | Manage providers | Full | None | | Booking oversight | Full | None | | Offer & affiliate management | Full | None | | View users | Full | None | | Full platform analytics | Full | Scoped + privacy-masked | | Blog management | Full | None | | Concierge & support | Full | None | | Import jobs | Full | None | | Audit logs | Full | Scoped to their college |

2. Platform Admin — Complete Reference

Navigation: Sign in → navigate to /Admin

The Admin Command Center is a tabbed interface covering: Overview · Colleges · Providers · Offers & Clicks · Dorm Policies · Verification · Users · Support · AI Usage · Experiments · Settings · Curated Colleges · Imports v2 · and more.

Standalone admin pages:

/AdminProviders — dedicated provider table with bulk import
/DormPolicyAIImport — AI extraction pipeline
/AdminDormPolicies — manual dorm policy CRUD + CSV
/AdminBlog — blog post management
/AdminAnalytics — full platform analytics
/AdminConciergeInbox — concierge request queue
/AuditTrail — audit log viewer

2a. College Directory Management

Adding a New College

Go to /Admin → Colleges tab → click Add College.
Fill in required fields: Name, City, State, Slug, Lat / Lon.
Optional: Aliases, Housing URL, Move-In URL, Move-In Window dates.
Click Save.

Warning: The normalizedName field is auto-computed and used for deduplication. Check the College Duplicates tab before bulk importing.

Archiving a College

Colleges tab → find the college → open detail view → click Archive.
Archived colleges are hidden from all public dropdowns but their data is preserved.
To restore: go to Archived Colleges tab → click Unarchive.

Warning (Irreversible): Deleting a college permanently removes the record and may leave orphaned policies, clicks, and offers. Use Archive instead.

2b. Dorm Policy Management

Policy Status Values

| Status | Meaning | |---|---| | college_provided | School explicitly provides this item | | school_endorsed | School officially partners with a provider | | not_listed | No mention in the source document | | prohibited | Explicitly banned | | unknown | Mentioned but status unclear |

AI Extraction Workflow (Recommended)

Navigate to: /DormPolicyAIImport

Select or search for the college.
Choose source tab: Paste Text, URL, or Upload PDF.
Click Auto-Run Extraction.
Monitor progress bar — extraction typically takes 30–90 seconds.
Once extracted: review rows, approve/unapprove, edit labels/categories as needed.
Click Publish to Dorm Policy (N items).

Warning (Irreversible): Publishing a job locks it permanently. To update policies, create a new import job.

Recovery options when publish fails:

Reconcile Counts — fixes metadata mismatches without re-extracting
Resume Publish — re-attempts publish using existing extracted rows
Re-link College + Notes — fixes broken collegeId references

CSV Upload Path

Navigate to: /AdminDormPolicies

Prepare CSV with columns: college_name, item_label, status, restrictions, source_url.
Upload the file, preview rows, click Confirm Import.

Warning: CSV matches colleges by exact name (case-insensitive). Pre-check your CSV against the colleges directory.

2c. Provider Management

Adding a Provider

/AdminProviders → Add Provider.
Fill in: Name, Category, Relationship (Partner / Affiliate / Listed), Website URL, Logo URL.
Click Save.

Bulk Import via CSV/Excel

Download the template by clicking the Download icon in the header.
Fill CSV with columns: name, category, relationship, affiliate_code, website_url, logo_url, short_desc, phone, email, service_cities.
Click Bulk Upload → select file.

Tip: Import deduplicates by normalized name. Re-importing a provider with the same name will update the existing record, not create a duplicate.

Provider Verification Workflow

Go to Admin → Verification tab.
Review pending requests — click Approve or Reject with a reason.
Verified providers get a badge on their public-facing cards.

2d. Offer & Affiliate Management

Creating an Offer

Admin → Offers & Clicks → Add Offer.
Fill in: Title, Category, College (blank = nationwide), Provider, Affiliate, Deeplink Template or External URL.
Click Save. Live immediately if active: true.

Campus-scoped: Set college_id. Appears only when that campus is selected.
Nationwide: Leave college_id blank. Appears as fallback for all campuses.

2e. User Management

Available roles:

| Role | Access Level | |---|---| | user | Standard student/family account | | admin | Full platform admin access | | provider | Provider Portal access | | University Admin (via UniversityAdmin entity) | Scoped university portal |

Warning: Setting a user to admin gives full system access. Do this only for trusted internal team members.

Creating a University Admin

University Admins are NOT created by changing the user's role field. Instead, create a UniversityAdmin entity record with: app_id, email, college_id, status: 'active'.

2f. Analytics Dashboard

Navigate to: /AdminAnalytics

| Metric | Source | |---|---| | Unique Devices | AnalyticsDaily.unique_devices | | Offers Clicked | AnalyticsDaily.offers_clicked | | Favorites Added | AnalyticsDaily.favorites_added | | Conversions | AnalyticsDaily.conversions | | Page Views | AppPageView | | Sessions | AppSession |

3. University Admin — Scoped Guide

Entry Point: /UAdmin

University Admins can:

View analytics for their assigned college(s) (with privacy masking below 5 unique devices)
Filter by date range and category
Export analytics CSV (when privacy threshold is met)
View the public campus page
View campus data completion scorecard

University Admins cannot:

Edit any data (policies, providers, offers, college details)
Access other colleges' data
See individual user identifiers or raw click data

4. Routine Admin Operations

4.1 Onboarding a New College Campus (End-to-End Checklist)

Check for duplicates (Admin → Name Duplicates tab)
Create the College record (required: Name, State, City, Slug, Lat/Lon)
Add Source Documents
Run AI Policy Extraction
Verify policy completeness (Curated Colleges tab)
Add Campus Intelligence (Intelligence Import tab)
Set up providers (/AdminCampusProviders)
Create campus-scoped offers
Review the public campus page (/Campus/[slug])
Assign a University Admin (if applicable)

4.2 Running a Dorm Policy Update Cycle

Locate the new policy source
Run a fresh extraction (/DormPolicyAIImport)
Compare new vs. old policies — pay attention to low confidence rows
Publish the new extraction
Archive outdated policies if needed

5. Troubleshooting & Known Issues

5.1 Import Job Failures

| Error | Fix | |---|---| | Text extraction returned insufficient content | Try Paste Text mode — copy-paste from the university page manually | | All URL fetches failed | URL may be behind auth or JS-rendered — try Paste Text or upload PDF | | AI output failed schema validation | Retry with Create New Import Job | | Job already running | Wait 2 minutes and try again |

5.2 AI Extraction Returns 0 Rows

Common causes:

Source document has no extractable policy content (e.g., a general welcome page)
URL points to a packing list, not a policy document

Debug steps: Expand Debug Details (Admin Only) on the job → review Debug Trace and Raw AI Output.

5.3 Common Gotchas

isLaunchReady not updating after publishing policies: Run Recompute Curated Colleges from Admin → Settings manually.
run_lock stuck on import job: Contact support to null out the run_lock field.
Dorm policy count mismatch: Use Reconcile Counts & Resume Publish.
College deduplication flag: Only one college per normalizedName should have isCanonical: true.

CollegeLogistics — Student & Family User Guide

Who this is for: Students heading to college and their families who want to plan smarter, pack right, and move in with less stress.

1. Welcome — What CollegeLogistics Does for You

Moving into college is exciting. It's also a lot of work.

There's the packing list, the dorm rules, the storage decisions, the flights home during breaks, the box shipments, the move-in day chaos — and almost none of it is explained clearly in one place.

CollegeLogistics was built to fix that.

Here's what the platform gives you — all in one place, all specific to your campus:

📋 Dorm policy lookup — Find out what's allowed, prohibited, or provided in your specific dorm before you pack a single box.
🚚 Logistics services — Browse and book storage, shipping, moving, and packing services that serve your campus.
✈️ Travel planning — Find flights, hotels near campus, and shuttle services for campus visits and move-in weekend.
🤖 AI assistance — Get instant answers about your campus, policies, and logistics.
🎯 Everything campus-specific — Select your school once and every recommendation, policy, and service offer is filtered to match your campus.

It's 100% free for students and families.

2. Getting Started

2a. Creating Your Account

You don't need an account to browse, but creating one unlocks the full experience.

Click Sign In in the top-right corner.
Choose Create an account and enter your email and password.
Check your inbox for a confirmation email and click the link inside.

2b. Selecting Your College

This is the most important first step. When you tell CollegeLogistics your school, the entire platform personalizes around it.

From the home page, type your school name into the search bar.
Click your school from the dropdown list.
You'll be taken directly to your Campus Guide.

Your college selection is saved so you don't have to re-enter it every visit.

2c. What You Can Browse Without Logging In

No login required:

The home page and general info
Campus Directory — browse and search all schools
Campus Guide previews — dorm policy summaries
Marketplace browsing — view service providers and offers
Blog — tips, guides, and move-in advice
Free downloadable resources (Move-In Checklist, Family Logistics Worksheet)

Requires a free account:

Full dorm policy details and policy search
Booking a service provider
Logan, the AI Concierge (the same AI in AI Search and the chat button)
My Stuff dashboard (bookings, favorites, reminders, rewards)

3. Dorm Policy Lookup

How to Search for a Specific Item

Navigate to your Campus Guide → Policies tab.
Use the search bar to type what you're looking for (e.g., "rice cooker," "candle," "fridge").
Matching policy items appear instantly.

Understanding Policy Status Labels

| Status | What It Means | |---|---| | ✅ Allowed | This item is permitted — bring it! | | ❌ Prohibited | This item is explicitly banned. Do not bring it. | | ⚠️ Restricted | Allowed under certain conditions. Read the details. | | ❓ Unknown | Policy is unclear or conditional. Contact your housing office. | | 🏫 Provided by School | Your school provides this item — no need to bring one. |

What "Restricted" Means

A Restricted item isn't banned — but it comes with conditions. Common restrictions include:

Size or wattage limits (e.g., "mini fridge must be under 4.0 cu. ft.")
Location rules (e.g., "microwaves only in floor kitchens")
Approval requirements (e.g., "space heaters require RA approval")

4. Finding & Booking Services

4a. Browsing the Marketplace

| Service | What It Covers | |---|---| | 📦 Storage | Summer storage, semester storage, on-campus programs | | 📬 Shipping | Ship boxes to campus or home at end of year | | 🚚 Moving | Local movers, full-service packing and moving help | | ✈️ Travel | Flights, hotels near campus, airport shuttles | | 🏨 Stays | Hotels near campus for family move-in weekend |

4b. Booking a Service

Find a provider → click Book Now or View Details.
Fill in: date, campus address, service type, special instructions.
Click Submit Booking.

Booking statuses:

| Status | What It Means | |---|---| | Pending | You submitted — waiting for provider confirmation | | Confirmed | Provider accepted your booking | | In Progress | Service is currently happening | | Completed | All done! | | Cancelled | Cancelled by you or the provider |

Tip: Book early — especially for move-in weekend. Popular storage and moving services fill up fast in August.

5. My Stuff Dashboard

My Stuff is your personal command center. Sign in and navigate to My Stuff to find:

Bookings — all services you've booked, with current status
Favorites — saved providers, offers, and campus guides
Reminders — custom alerts so nothing slips through the cracks
Documents & Receipts — upload confirmations and booking docs
Rewards Points — your points balance and earning history
Recent Activity Feed — a timeline of everything you've done on the platform

6. AI Features

6a. AI Campus Intelligence

Each Campus Guide includes an AI-generated summary covering: housing overview, move-in info, key policies, local context, and parking & transportation.

Important: AI campus summaries are generated from publicly available sources. Always verify critical details directly with your school's Housing or Residential Life office.

6b. Logan, the AI Concierge

Available from the navigation or the floating chat button on many pages.

Great questions to ask:

"What storage options are available near [my school]?"
"Can I bring a Keurig to my dorm?"
"What should I ship ahead vs. bring on the plane?"
"When does move-in usually happen for freshmen?"

7. Concierge Services

The Concierge is ideal when you have a complicated logistics situation and want a human to review your options and coordinate.

How to submit a request:

Click Concierge Services in the navigation.
Fill in the intake form: services needed, college, move-in date, how much help you want, contact info.
Click Submit.

A team member will reach out via email or phone within 1–2 business days.

8. Tips for a Smooth Move-In

Check dorm policies BEFORE you pack — look up every appliance before packing it.
Book storage early — many campus programs open for booking in February or March.
Know your move-in window — most schools assign a specific time slot.
"Restricted" doesn't mean you can't bring it — read the conditions.
Ship ahead when possible — usually cheaper and less stressful than airline fees.
Confirm what the school actually provides in your room before ordering from Amazon.
Have a move-out plan before move-in — if you'll need storage over summer, book early.

9. Frequently Asked Questions

Is CollegeLogistics free to use?
Yes, completely. The platform makes money through affiliate partnerships — when you book through an offer link, we receive a small commission from the company at no cost to you.

Are the providers on the platform vetted?
Providers with a blue Verified badge have submitted business documentation and passed a review. Always read reviews and do your own research before booking.

What if my college isn't listed yet?
Look for the "College not listed?" link on any page with the college search. Submit your school's name and our team will prioritize adding it.

What if a dorm policy is wrong or outdated?
Click "Was this policy helpful?" or the feedback link on the policy card to flag it. Always confirm with your school's housing office for anything that affects packing decisions.

How do I cancel a booking?
Go to My Stuff → Your Bookings → click on the booking → click Cancel Booking.

I'm a parent helping coordinate the move — is this platform for me too?
Absolutely. You can create your own account and use everything the student does.

The AI gave me wrong information about my school's policy. What do I do?
Logan is a helpful starting point, not a substitute for official school information. Always verify with your school's official housing website or Residential Life office.

Questions not answered here? Visit our Help Center at /help or reach us via the Contact page.

CollegeLogistics — Documentation