ClearPath

ClearPath turns confusing school and support documents into plain-language summaries, deadlines, action steps, and questions to ask a human expert , so people can move from confusion to action faster.

Comment

ClearPath

Inspiration

Navigating the education system and civic bureaucracy is a nightmare. Between school policies, complex enrollment forms, and hidden deadlines, the sheer density of official documents is overwhelming for students and parents alike. As students ourselves, we've watched our peers and families struggle to decode bureaucratic jargon just to figure out what their next step is.

We didn't just want to build another AI summarizer. We wanted to build ClearPath: a highly resilient, autonomous engine that reads confusing documents, extracts the actionable deadlines, verifies them against official government and educational databases, and generates a crystal-clear action plan.

What it does

ClearPath takes complex civic or educational documents and transforms them into localized, verified action plans.

When a user uploads a file, the application processes it through a rigorous 5-stage pipeline:

  1. Processing Document Structure
    Breaking the text into hierarchical trees.

  2. Extraction
    Pulling critical deadlines, requirements, and required actions.

  3. Human-in-the-Loop (HITL) Verification
    Pausing the engine so the user can verify the extracted facts and set strict regional boundaries.

  4. Cross-Referencing
    Launching an autonomous web agent to verify the claims against official .gov, .edu, and .org domains.

  5. Synthesis
    Generating a final, safety-checked action plan.

For regular users, this happens behind a beautiful, calm progress UI. But for developers, opening the /analysis route's developer toggle reveals a live, high-density telemetry stream broadcasting over 220+ micro-milestones — including live token-streaming deltas — directly from our background workers.

How we built it

We engineered ClearPath as a highly resilient distributed system, optimized on our Ubuntu environments using pnpm for rapid monorepo management.

  • Frontend: Built with Next.js (App Router) and Tailwind CSS, utilizing SWR for lightning-fast cache hydration and state recovery.
  • Backend: A high-performance Fastify API layer backed by a robust PostgreSQL state machine.
  • Task Queuing: To protect our Node.js event loop, we utilized Redis and BullMQ to handle backpressure and task delegation.
  • Real-Time Telemetry: A custom Server-Sent Events (SSE) pipeline that intercepts token streams mid-flight and broadcasts granular updates to the client.

Challenges we ran into

Building a production-grade architecture in a hackathon setting meant hitting serious bottlenecks:

  • Compute Choking: Initially, running hierarchical tree-based chunking and vector generation crashed our event loop.
    Fix: We implemented strict backpressure management, shifting the heavy lifting entirely onto our external Hugging Face Space and managing the traffic via Redis/BullMQ.

  • Network Drops & State Loss: Deep RAG takes time, and standard socket connections lose data if a user's internet drops.
    Fix: We built a zero-loss hydration engine. If a browser disconnects, our Fastify route queries the Postgres state machine and replays the entire 260+ log history down the SSE pipe.

  • Search Agent Failures: Our autonomous web-search agent initially failed with HTTP 400 errors because it lacked local context for official databases.
    Fix: We built a Human-in-the-Loop (HITL) pause state, forcing the system to wait for explicit country/region verification from the user before executing the search array.

  • Multi-Device Race Conditions: With the HITL workspace active, simultaneous edits across devices caused race conditions.
    Fix: We wrapped database updates in strict PostgreSQL transactions and built a pub/sub fan-out system. A status change on a phone instantly wakes up and syncs the live stream on a desktop without a reload.

Accomplishments that we're proud of

We are incredibly proud to have architected an enterprise-grade distributed state machine as young developers. Going beyond basic API wrappers, we built:

  • A non-blocking ingestion engine that can handle massive simultaneous traffic spikes.
  • A multi-device synchronization mesh that feels as seamless as tools like Figma or Linear.
  • A beautiful UX/DX balance: giving parents a clean, predictable UI while exposing our raw, low-latency background telemetry logs for technical audits.

What we learned

We learned that building a real-world AI application is fundamentally an exercise in distributed systems engineering. We learned how to manage backpressure, how to protect a single-threaded runtime using message brokers, and why maintaining a highly consistent database state is mandatory when dealing with asynchronous stream parsing.

Most importantly, we learned that sometimes the best AI feature isn't more autonomy — it's knowing exactly when to pause the queue and ask a human for direction.

What's next for ClearPath

Moving forward, we plan to expand our document parsing to handle complex, messy image-based PDFs (like scanned school enrollment forms). We also want to integrate native multi-language translation at the edge, ensuring that immigrant parents can feed English bureaucratic documents into the system and receive verified, step-by-step action plans entirely in their native language.

Built With

Share this project:

Updates