Signal-Scout

Inspiration

Hackathon builders often spend valuable time translating dense rules, judging criteria, and scattered documentation into concrete project decisions. It is easy to overlook a requirement, misunderstand category alignment, or spend limited time building something that will not strengthen the final submission. I created Signal Scout to address that problem. I wanted a collaborative agent that could inspect official hackathon information alongside evidence from a builder’s public project, identify the most important gaps, and turn them into practical next steps. This was also my first project deployed end-to-end on Google Cloud. Building Signal Scout gave me a practical reason to learn cloud deployment, persistence, credentials, logging, scaling, and cost controls while solving a problem I was experiencing myself.

What it does

Signal Scout turns an official hackathon page, builder context, and optional public GitHub repository into a sourced project-readiness analysis. It runs a bounded agent loop: Retrieve the approved public sources. Separate event evidence from project evidence. Extract requirements and judging criteria with Gemini. Validate the structured response, citations, and project-state claims. Compare the requirements with available repository evidence. Produce sourced strategic gaps, a learning shortlist, uncertainties, an actionable build plan, and a Field Report. Accept one explicit feedback turn from the builder. Adapt one recommendation, explain what changed and why, preserve its supporting sources, and ask one targeted clarification. The interface exposes an Activity trail showing when sources are checked, collected, analysed, validated, and synthesized. Live results are clearly separated from the deterministic mock experience. Signal Scout is intentionally bounded. It is not presented as a general chatbot, unrestricted crawler, or multi-agent system.

How we built it

I built the frontend with React, TypeScript, and Vite. A Node.js and Express backend owns retrieval, model calls, validation, persistence, cancellation, retry limits, feedback adaptation, and public usage controls. Gemini 3.5 Flash is accessed through the Google GenAI SDK. The model produces structured JSON, which is checked with Zod before being exposed to the user. A second semantic-validation layer verifies citation URLs, distinguishes event and project evidence, detects unsupported project-state claims, preserves established technology constraints, and rejects recommendations that contradict work the builder has already completed. Firestore Native persists scan requests, collected sources, Activity events, validated analysis, errors, and the bounded feedback result. I packaged the application as a Node 22 container and deployed it on Cloud Run. Gemini credentials remain server-side through Secret Manager and a dedicated runtime service account. The public demo only accepts event URLs from Devpost and project URLs from GitHub. Redirects are revalidated, private or local network targets are rejected, and retrieval is constrained by time, response type, and response size. To control costs, scan creation, analysis retry, and feedback actions pass through daily and per-client usage guards. Cloud Run scales from zero to a maximum of two instances, and the Google Cloud project has a monthly alerts-only budget with multiple spending thresholds.

Challenges we ran into

One of the hardest problems I encountered was distinguishing event requirements from evidence about the current project. An event page can prove what a submission requires, but it cannot prove whether a repository already satisfies that requirement. I addressed this by assigning every source an evidence role and requiring both event and project citations when a finding combines those claims. Public webpage retrieval was another challenge. Devpost and GitHub pages contain navigation text, browser warnings, and other boilerplate. They may also respond slowly or fail temporarily. I added strict retrieval boundaries and honest partial-result handling. If the official event source is unavailable, Signal Scout preserves any collected project evidence but withholds event analysis rather than deriving requirements from the wrong source. I also encountered recommendations that treated completed deployment work as unfinished. I strengthened the prompting and semantic validation so explicitly completed Cloud Run work cannot be returned as a new deployment task. The agent can still recommend capturing or presenting proof of that work when it matters to the submission. Other challenges included protecting credentials, preventing late worker writes from overwriting cancellation, bounding retries and feedback, supporting narrow mobile viewports, and presenting enough technical detail for debugging without overwhelming the user.

Accomplishments that we're proud of

I am proud that Signal Scout became a complete, publicly deployed agent workflow rather than remaining a mock interface. The final system: Runs Gemini 3.5 Flash through the Google GenAI SDK. Persists structured agent state in Firestore. Runs publicly on Cloud Run with server-side credentials. Grounds findings in separate event and project evidence. Shows a visible Activity trail instead of hiding the agent process. Produces requirements, strategic gaps, learning recommendations, a build plan, uncertainties, and a Field Report. Supports one sourced feedback adaptation with a clear “Changed because” explanation. Fails closed when evidence or model validation is insufficient. Protects the public demo with host restrictions, DNS checks, usage limits, scaling limits, and budget alerts. Works across desktop, tablet, and narrow mobile layouts. Reproduces from a clean clone using the documented setup instructions. I am especially proud that the corrected golden workflow completed with both Devpost and GitHub evidence and produced only genuinely outstanding submission tasks. It did not incorrectly recommend repeating deployment work that was already complete.

What we learned

This project taught me how the different parts of a cloud-hosted agent fit together: model access, structured outputs, validation, persistence, retrieval, identity, secrets, logs, deployment revisions, scaling, and cost controls. I learned that valid JSON is not necessarily a trustworthy result. A response can satisfy its schema while still containing an unsupported, weakly sourced, or contradictory conclusion. Evidence roles, semantic validation, uncertainty, and fail-closed behavior became as important as the model call itself. I also learned that useful agentic behavior does not require unlimited autonomy. Signal Scout is strongest when its loop is visible and constrained: collect real evidence, generate a grounded plan, accept explicit feedback, explain the adaptation, and stop at a clear boundary. Finally, completing my first end-to-end Google Cloud project made cloud infrastructure much more concrete. Cloud Run, Firestore, Secret Manager, service identities, logs, and budget controls became connected parts of one working system rather than isolated services.

What's next for Signal-Scout

My immediate next step is completing the final demonstration and submission while keeping the verified runtime frozen and reliable. After the hackathon, I would like to explore: Moving in-flight work to a durable queue so scans can recover across container interruptions. Improving extraction so evidence previews contain less navigation and webpage boilerplate. Supporting additional carefully approved public-source types. Adding reusable domain packs for grants, accelerators, challenges, and other structured opportunities. Expanding evaluation coverage for retrieval quality, grounding, and recommendation usefulness. Improving accessibility testing and the presentation of long reports. Exploring additional feedback steps while preserving explicit user control and clear limits. Adding authentication and per-user quotas if Signal Scout evolves beyond a bounded public demo. My long-term goal is to make Signal Scout a reusable evidence-to-action partner for builders navigating unfamiliar opportunities, not just a tool for one hackathon.

Built With

• api
• docker
• express.js
• firestore
• gemini
• github
• node.js
• typescript
• vite
• vitest
• zod