Welcome, Future Teammate!

Hey there! Thanks for taking the time to do this exercise. We've designed it to be a fun and challenging way to get a feel for the kind of work we do here. It's a chance for you to showcase your skills as a builder, problem-solver, and mentor across the full stack.

This isn't a typical coding test with a single right answer. We're much more interested in your thought process, how you handle trade-offs, and your ability to navigate a pre-existing (and slightly imperfect) codebase using a realistic Git workflow.

A Quick Note on Time: We estimate this exercise could take between 2 to 4 hours. However, we've intentionally included more work than can be done in that time. Please do not feel pressured to complete everything. Prioritization is a key skill, and we want to see how you approach a task with real-world time constraints.

The Scenario: A FinTech Transaction Dashboard

You've just joined a new team building a dashboard for visualizing financial transactions. The application is composed of a Python (FastAPI) backend and a React (TypeScript) frontend. Your mission is to get familiar with the codebase, review a teammate's contribution, fix some underlying issues, and then build out a new feature.

---

Your Mission: A Three-PR Workflow

Important First Step: Before you begin, please fork this repository (Make sure you fork all the branches, you will need them).

You will work entirely on your own fork, creating pull requests within that repository. Do not create any pull requests to the original upstream repository.

Your work will be organized into three separate pull requests within your own repository. We recommend following these steps in order.

A Quick Glossary of Branches

• main: The initial state of the codebase. You will branch from here.
• fix-bug-666: A simulated PR from a junior developer. This branch contains their work for you to review.
• fix/haunted-codebase: The branch you will create from main to fix the existing technical debt.
• feature/transaction-tags-grid: The branch you will create from fix/haunted-codebase for the new feature (database migration and data grid).

Step 0: Getting Up and Running

1. Clone Your Fork: Clone your newly forked repository to your local machine.
2. Set Up Environment: We've included a docker-compose.yml file for setup. You'll need to create a .env file from the .env.example template.
3. Launch the App: Run docker-compose up --build. This will spin up the backend, frontend, and database. The database will be automatically seeded with initial data the first time it starts.
4. Explore: The frontend is at http://localhost:3000 and the API docs are at http://localhost:8000/docs. Get a feel for the app and the code on the main branch.

Running Tests

We have set up a comprehensive testing suite for this project. A helper script is provided to run all tests and install any necessary dependencies automatically.

From the root of the ns-python-react-exercise directory, run the test script:

./run-tests.sh

This will execute the backend tests (unit, integration, E2E) and the frontend Playwright E2E tests.

PR #1: The Code Review

Your first task is to act as a mentor and review a "PR" from a junior developer.

1. Understand the Context: The junior dev's work is on the fix-bug-666 branch. On that branch, read the BUG-666.md file to understand the original problem.
2. Open the PR: In your own repository, open a pull request from fix-bug-666 to your main branch. Use the PR description template below.
3. Perform the Review: Go to the "Files Changed" tab of the PR you just created. Leave comments directly on the code, providing a mix of high-level architectural feedback and specific line-by-line notes.
4. Abandon the PR: Once your review is complete, close the pull request without merging.

PR #1 Description Template

### What I Did
This PR fixes the transaction display bug by filtering transactions on the frontend to only show relevant entries. I've also implemented server-side pagination for better performance.

### How to Test
1. Checkout this branch.
2. Run `docker-compose up --build`.
3. Navigate to the frontend at `http://localhost:3000`.
4. Observe that only relevant transactions are displayed.
5. Verify that pagination controls are now active and functional.

### Architectural Decision Record (ADR)
To address the display bug, I decided to handle filtering directly in the frontend component. This approach simplifies the backend and leverages the client's processing power for a snappier user experience. For pagination, I added a new `GET` parameter `page` and `page_size` to the existing `/api/v1/transactions/` endpoint, and updated the frontend to send these parameters.

### AI Usage Summary
I used AI tools for minor code refactoring and to generate some boilerplate for the frontend pagination component.

PR #2: Fixing Technical Debt

Now, it's time to fix the other bugs lurking in the main branch.

1. Create a Branch: From your main branch, create a new branch. We suggest fix/haunted-codebase.
2. Hunt the Bugs: Investigate the following reports:
   • Backend Report: "Users are reporting that the main transaction list is loading very slowly, especially for users with many transactions. Our initial investigation suggests the API endpoint might be making an excessive number of database calls."
   • Frontend Report: "The product owner noticed that when they hover over their user profile icon in the header, the main data grid seems to flicker and re-render, even though the data hasn't changed. This is causing a sluggish feel on the dashboard. The React Profiler might be useful for confirming this."
3. Open the PR:
   • Open a new pull request in your repository from fix/haunted-codebase to main.
   • Use the PR description template for PRs #2 and #3 below.
   • Leave this pull request open for us to review.

PR #3: New Feature Development (Stacked PR)

With the codebase stabilized, you can now build the new feature. This PR will be "stacked" on top of PR #2, meaning it builds directly on the changes made in fix/haunted-codebase.

1. Create a Branch: From your fix/haunted-codebase branch, create a new branch. We suggest feature/transaction-tags-grid.
   • Note: Because this is a "stacked" PR, you will see the commits from your fix/haunted-codebase branch also included in this pull request. This is expected.
2. The "Twist": The new feature requires a database change. The current schema has a one-to-one relationship, but the feature needs a one-to-many relationship. Design and execute this migration first.
3. Build the Feature:
   • Backend: Create a new API endpoint that uses a raw SQL query with a multi-table JOIN.
   • Frontend: Build a data grid with server-side sorting and pagination.
4. Open the PR:
   • Open a new pull request from feature/transaction-tags-grid to your main branch.
   • Use the PR description template for PRs #2 and #3 below. In your description, please explicitly mention that this PR builds on fix/haunted-codebase and link to PR #2.
   • Leave this pull request open for us to review.

---

The Deliverable

The final deliverable is a link to your forked repository. When you submit it, we expect to see the following:

• PR #1 (Code Review): A closed pull request from fix-bug-666 to main, containing your review comments.
• PR #2 (Bug Fixes): An open pull request from fix/haunted-codebase to main, containing the fixes.
• PR #3 (New Feature): An open pull request from feature/transaction-tags-grid to main, containing the database migration and the new data grid feature. This PR will implicitly include the commits from PR #2 as its base.

PR Description Template for PRs #2 and #3

For PRs #2 and #3, please use this template:

### What I Did
(A brief summary of the changes in this PR.)

### Depends On
(If this PR builds on another, like PR #3 builds on PR #2, link it here.)

### How to Test
(Clear instructions on how to test the changes in this PR.)

### Architectural Decision Record (ADR)
(A short explanation of significant decisions. For PR #3, this should cover the DB migration and state management.)

### AI Usage Summary
(A high-level summary of how you used AI tools.)

---

Good luck, and have fun! We're excited to see your work.