# Gun Trafficking Tracer: Product Requirements Document Version 4: October 12, 2025 ## 1. Overview Gun Trafficking Tracer is an application focused on combating gun trafficking. It helps citizens identify Federal Firearms License (FFL) dealers that may contribute to the trafficking of firearms and provides tools to take action and reduce illegal gun trafficking. --- ## 2. Application Structure The application is organized into a single primary view to provide a distinct user experience: * **FFL Directory:** The main interface for searching, filtering, and browsing the list of FFLs. This view is designed for targeted investigation and information gathering on specific dealers. --- ## 3. User Journeys The application supports the following critical user journeys: * **Search and Filter:** Find FFLs by name, city, state, or license status. * **Violation-Based Search:** * Find FFLs with the most violations. * Find FFLs with a specific type of violation. * **Detailed Browsing & Action:** Browse a one-page listing for each FFL that provides a snapshot of key statistics and use AI-powered tools to generate outreach scripts for contacting officials or leaving public reviews. These user journeys are supported by familiar UI patterns like faceted search and dropdown menus. --- ## 4. Features ### 4.1 FFL Directory The primary view for interacting with the FFL data. #### 4.1.1 Filter, Sort, and Search * **Search Bar:** For finding FFLs by name or city. * **Filters:** Comprehensive options including License Status and State. * **Violation Type Filter:** A prominent, symmetrical grid of buttons that makes all violation types visible at once for easy selection. * **Sorting:** Options to sort by name or number of violations. ### 4.2 FFL Listing Pages Each FFL has a dedicated detail page that provides comprehensive information. #### 4.2.1 Information Displayed * **Business Name & Address**: The official name of the FFL and its location. * **Contact Information:** Phone number and email, if available. * **Violation History:** A summary and detailed list of all recorded ATF violations. * **Government Contacts:** Contact information for the district's U.S. Representative, both U.S. Senators, and the relevant state-level firearms authority or Governor's office. #### 4.2.2 Calls-to-Action (CTAs) * **View Business Listing on Google Maps:** A prominent button that links directly to the FFL's Google Maps page. * **View ATF Reports:** A direct link to view the official ATF violation reports in a public cloud repository. This link must open a web-accessible view of the PDF files in the google cloud storage bucket. * **Report Suspicious Activity:** A modal with pre-defined options for reporting activities like straw purchases and direct phone numbers for local police and the ATF. * **AI-Powered Outreach Script Generator:** A powerful modal that uses AI to generate tailored outreach scripts for phone calls, emails, or online reviews, complete with relevant contact information and a "copy to clipboard" function. ### 4.3 AI-Assisted Outreach To empower users to take effective action, the application integrates AI to generate communication scripts. * **Format Selection:** Users can choose to generate a script for a phone call, an email, or an online review. * **Context-Aware Generation:** The AI prompt is dynamically populated with the specific FFL's name, location, and violation history to create relevant and factual content. * **Structured Output:** All generated scripts follow a best-practice structure: Intro as a constituent, Summary of concern, Facts about the dealer, a clear Action request, a request for Follow-up, and Gratitude. * **Format-Specific Tuning:** Generated content is tailored for the selected format (e.g., conversational for calls, professional with links for emails, 100-200 words and objective for reviews). * **Integrated Contacts:** The generated script is presented alongside the appropriate contact information to streamline the user's workflow. Effective outreach usually follows this general flow: * **Intro**: Let the person you are contacting know that you are a local constituent. This is important to distinguish you from national outreach. You are a voice and vote that matters in the community. * **Summary**: Simple statement on why you are contacting this office * **Facts**: Share a couple of factual pieces of supporting evidence and examples of the impact on the community and on you * **Action**: Nail down specific actions the office can do to help address this issue ASAP (today, this week). If there is pending legislation, votes, policy decisions, or investigations, bring those up. * **Follow up**: Ask for a call back or email in a week with an update * **Gratitude**: Thank them for their time. In addition the the general flow, use the following guidance for specific formats * Calls * Use simple conversational language that is natural for the person calling * Avoid jargon * When talking live to someone, ask questions * The script should be able to used to leave a voicemail. * Emails * Provide links to references with more details, e.g. ATF policies, CFR violations, e.g. https://regulations.atf.gov/478 * Provide a link to the business website or online reviews * Online Reviews * Use professional language -- avoid inflammatory statements * Aim for a review lengths between 100 words and 200 words, which is based on guidance from this analysis: https://www.sterlingsky.ca/length-google-review-matter ### 4.5 About this App * **Access:** A clearly visible "About" text button in the header opens a modal window. * **Content:** The modal provides a user-friendly overview of the application's purpose and key features. --- ## 5. Key Definitions ### 5.1 ATF Zero Tolerance Policy Violations The application data includes violations that may fall under the ATF's "Zero Tolerance" policy, such as: 1. Transferring a firearm to a prohibited person. 2. Failing to conduct a required background check. 3. Falsifying records, such as a Firearm Transaction Record (Form 4473). 4. Failing to respond to an ATF tracing request. 5. Refusing to permit the ATF to conduct an inspection. The violation filters in the app are generated from the summary descriptions provided in the public dataset. --- ## 6. Data ### 6.1 FFL Data The app is pre-populated with a comprehensive list of FFLs from a public dataset, including their violation histories and contact information for state and federal government officials. Do not generate any mock data. All the FFL data for the app can be found in gs://atf-state-ffl as separate JSON files by each state. Use the data from cloud storage as much as possible to ensure scalability and avoid overrunning limits. ### 6.2 Data Architecture The application's data architect will need to support the following requirements * Support over 3000 FFLs across all 50 states * Some states like Texas will have hundreds of FFLs and the data may need to be split across multiple sources * Data for some states and FFLs will be updated independently of other FFLs and should not trigger a reprocessing of all FFL data * **Asynchronous UI:** The application's UI (hooks and pages) must handle asynchronous data flow, correctly displaying loading spinners and error messages. * Compress FFL data and minimize data duplication * Generate URLs dynamically in the app where possible to minimize storing redundant information, e.g. links to google maps can be generated dynamically using the address of the business Suggested implementation details * **Dynamic On-Demand Loading:** The data service should use async import methods to load state modules only when a user selects that state. This is highly performant and scalable, as it creates separate "chunks" that are only downloaded when needed. * Data as Modules:  Each state's data must be an independent module * Future-Proof Manifest:  Define a file which data files belong to each state. This design anticipates that a large state could have its data split across multiple files (e.g., tx-part-1.ts, tx-part-2.ts) for even better performance. 3. --- ## 7. Design & Theme * **Theme:** Dark theme for improved readability and a modern aesthetic. * **UI Components:** Inputs, text, and modals are styled for clarity and alignment. --- ## 8. Product Requirements & Release Notes Act as a Product Manager: Your role is to meticulously document changes to this application in the form of product requirements. You will be provided with my descriptions of changes. Identify the User and the Goal: For each change I describe, first identify the target user (e.g., "As a new user," "As an admin") and their primary goal. Frame this as a user story: "As a [user type], I want to [action] so that [benefit]." Detail the Changes and Acceptance Criteria: Document the specific changes made to the application. List these as bullet points under "Changes." Then, create a corresponding list of "Acceptance Criteria" which are the specific, testable outcomes that must be true for the requirement to be considered complete. Capture UI/UX Modifications: If the change involves the user interface or user experience, describe the "before" and "after" states. Note any changes to buttons, menus, workflows, or visual elements. Maintain a Consistent Format: Present each documented requirement in the following structure: * User Story: * Changes: * Acceptance Criteria: * UI/UX Notes: Ask Clarifying Questions: If my description of a change is ambiguous, ask specific questions to clarify the user, their goal, or the expected outcome before documenting the requirement.