Project overview

The class will build the TrityShield Web Console: a browser app where SOC analysts review scam and phishing verdicts, triage them, and report trends. The backend already exists.

What TrityShield is

A scam and phishing detector for university students. Users connect Gmail or Outlook, paste messages, upload screenshots, or forward content through Telegram and WhatsApp bots. Each item gets a verdict:

• Label: safe, suspicious (score 35 or more) or dangerous (score 70 or more), on a 0–100 score.
• Scam type: phishing, job_scam, advance_fee, impersonation, payment_fraud, prize_scam, investment_scam, romance_scam, rental_scam, malware, extortion, other, or none.
• Evidence: human-readable reasons, plus signals tagged by source (heuristic, link reputation, or AI model).

What already exists

Five Go microservices behind a Caddy HTTPS gateway: auth, user, detection, email and bots. Each has a REST/JSON API with an OpenAPI spec, browsable in Swagger UI at /docs/. The server is live and the UI design is finished. The frontend is what is missing.

What the class builds

A web console that turns these verdicts into SOC work: a triage queue, case detail with evidence, analyst feedback on verdicts, and dashboards of scam activity.

Getting started

The server is live and the design is finished, so the team builds the real console from day one. There is no mock-server stage.

1. Clone the starter repository (link at the top of this page).
2. Choose your frontend stack together (see Technology choice) and set up the initial project inside the repo.
3. Put the API base URL, https://trityshield.nohup.me, in one config file, not scattered through the code.
4. Register your own test account with POST /auth/v1/register and a made-up email address. Read the request rules before you start calling the server.
5. Work on branches and review each other's changes before merging.

Purpose and objectives

The project gives students hands-on SOC triage practice on real detection output, while producing a console the product can use.

Learning objectives

By the end, each student can:

1. Triage a phishing or scam alert from its evidence: sender, subject, reasons, signals and score.
2. Explain why a verdict is right or wrong, and record a false positive or false negative with a justification.
3. Map common scam types to MITRE ATT&CK techniques (for example T1566 Phishing) and to a response action.
4. Read an OpenAPI spec and integrate a web client with an authenticated REST backend.
5. Apply secure web practices: token handling, least privilege, input validation, OWASP Top 10.
6. Write an incident report and a weekly threat summary for a non-technical audience.

Product objectives

The console must:

1. Show analysts a prioritised queue of suspicious and dangerous verdicts.
2. Capture analyst feedback that can be used to tune the scoring thresholds.
3. Report trends: volume by label, scam type, channel and time.
4. Never expose more user data than the backend already keeps (previews, not full messages).

Scope

The class owns the web console frontend only. The backend is live and belongs to the instructor.

In scope

Out of scope

• Changes to the backend, the detection engine, scoring rules or AI prompts.
• Redesigning the UI. The design is final.
• Connecting real student mailboxes. Use test accounts and made-up messages only.
• Production deployment to the live server. The team runs the console locally and in the demo.
• Storing full message bodies or screenshots. The backend deliberately keeps only a short preview.

Technology choice

The team chooses its frontend stack. Pick one of four options, the same one for everyone, and write the choice in the README.

• Pick what most of the team can already use.
• Decide by the end of week 1. No switching stacks after that.
• Whatever the stack, the UI must match the design at design.nohup.me.

Backend API and integration

The server is live at https://trityshield.nohup.me. The full contract is in the Swagger documentation at trityshield.nohup.me/docs, which covers the auth, user, detection, email and bots services. The console calls the same address over HTTPS, using REST/JSON.

Conventions

• Auth: Authorization: Bearer <token>. Tokens are opaque (not JWT), last 30 days, and have no refresh token. On a 401, send the user back to login.
• Errors: {"error": {"code", "message", "field", "request_id"}}. Show message; log request_id.
• Paging: ?limit=1..100&cursor=, responses are {items, next_cursor}.
• Rate limits: login and register 10 per minute per IP; analysis 12 per minute per user. Handle 429 gracefully.
• Retention: verdicts are purged after 90 days.

Endpoints the console uses

Paths start at the base URL, for example https://trityshield.nohup.me/auth/v1/login.

What the API does not offer today

The API serves each signed-in user's own data only. The console therefore works from the verdicts of the account it is signed in with. These are not in the API today:

• Analyst or admin roles
• Listing verdicts across all users
• Storing case status, assignee and notes
• Aggregate statistics for the dashboard
• An audit log of analyst actions

The team does not wait for these. Build from what the API returns now, keep case status and notes in the browser, and tell the instructor in week 1 if a feature truly needs one of them.

Request rules: keep your requests low

The server is shared by the whole class, and every analysis call behind it costs money. The Swagger "Try it out" button sends real requests too, so the same rules apply there.

• Log in once and keep the token. It lasts 30 days. Never log in on every page load or every test run.
• Login and register are limited to 10 per minute per IP address, and the whole class may share one address. Do not retry failed logins in a loop, and stagger your sign-ups.
• Analysis is limited to 12 per minute per user, and each call costs money. Run it only when a person clicks the button, never automatically, in tests or in loops. Use short made-up messages.
• Ask only for what you need. Use limit and cursor, load the next page only when the user asks, and never fetch every page on load.
• Debounce filters and search by at least 300 ms, and keep results in memory instead of requesting the same list again on every screen change.
• Do not poll faster than once every 30 seconds, and stop polling when the tab is hidden.
• On a 429 response, stop and wait. Retry at most twice, with a longer pause each time.
• Do not scan, load-test or script bulk calls against the server, and do not call /internal/ paths.
• Automated tests use saved sample responses (JSON files), not the live server.

Deliverables and acceptance criteria

The team hands in six deliverables. A deliverable is accepted only when every criterion in its row is met.

Quality bar for the console

• Works in current Chrome, Firefox and Safari, at 1280 px and wider.
• Shows a clear state for loading, empty, error and rate-limited (429) responses.
• Logs out on 401 and never stores the token in a URL.
• Escapes all message previews, subjects and sender names: they come from attackers.
• Stays within the request rules in the Backend API section.

Team structure and roles

Everyone on the team is a frontend developer. Building the console is mandatory for all. On top of that, each person can take one extra role. The instructor is the project sponsor and not part of the team: they provide the server and API changes, approve scope changes and grade.

Extra roles are on top of frontend work, not instead of it. The team agrees who takes each one and records it in the README by the end of week 1.

How the team lead is chosen

The team lead is chosen by a digital vote, held in week 1. Press Vote next to Team lead, or open the Vote tab.

1. Pick one student from the list. If your name is not on the list, add it first. Your name is all that is needed.
2. Each person votes once and can change the vote until voting closes.
3. The instructor closes voting. The student with the most votes becomes team lead, and the page shows who was picked.
4. After a tie, the instructor re-runs the vote.
5. The instructor is not on the list, cannot vote and cannot be picked.

Milestones and timeline

The project runs 6 weeks. It starts now, in week 8 of the term, and ends around week 14. The team moves to the next phase only after passing its gate. The week numbers below count from the start of the project.

The console uses the live API from the first day. If a Must feature is at risk, drop Could items first.

Constraints, risks and rules of engagement

Rules of engagement

These are pass or fail. Breaking one stops the team's access to the class environment.

• Use only test accounts and synthetic or public sample messages. Never connect a real personal or university mailbox.
• Do not attack, scan or load-test the backend, the live server or third-party services (Google, Microsoft, OpenRouter, Telegram, WhatsApp). Keep to the request rules.
• Never commit tokens, API keys or .env files. Rotate anything leaked and tell the instructor the same day.
• Treat every preview, subject and sender as hostile: never open the links, always escape them on screen.
• Report any security bug you find in the backend privately to the instructor, not in public channels.

Assumptions

• Students know HTML, CSS and JavaScript. The stack is the team's choice: React, Vue, Angular, or plain JavaScript with HTML.
• The server is live and the design is final, so the team spends its time on the frontend.
• Analysis calls the AI provider, so each call costs money. Follow the request rules.
• The project runs 6 weeks from now.

Risks

Communication, grading and sign-off

Communication

• Weekly 15-minute check-in between the team and the instructor: done, next, blocked.
• API questions and backend bugs go to the instructor in writing, with the request_id from the error.
• Scope changes need the instructor's written approval.

Grading

Sign-off

Each team member signs to confirm they have read this charter and the rules of engagement. The names come from the vote list.