Feedback on Events Startup Project (Backend)

[adamblanchard]

The project has been tested by a some mentor(s) before we run this for the first time with trainees. We will also collect feedback after we run it with trainees. For now, this task contains a dump of any feedback collected so far.

Items in here are welcome to be discussed or picked up. Note that any changes made now can be merged to the project template repo, but won't end up in the trainees projects (unless they actively decide to sync with the parent fork, or we find a major issue that we need to request trainees merge in).

---

Feedback from Yana (slack)

• 1. No PostgreSQL setup instructions in the skeleton

  The spec requires PostgreSQL, but the root README.md only shows a MySQL command. This gives students setup instructions for the wrong database.

  Suggestion: Add a PostgreSQL example and clearly state that PostgreSQL is required.

• 2. .env-template

  The .env-template includes:

  DB_PORT=330

  This is incorrect. It should be 3306 for MySQL or 5432 for PostgreSQL. 330 is not valid for either, so it is likely to confuse students.

  Suggestion: Default the template to PostgreSQL, or add a clear comment explaining which section should be used for this project.

• 3. npx knex migrate:make does not work

  A student looking up how to create a Knex migration will likely try:

  npx knex migrate:make create_user_table

  After adding a migration name, this fails with:

  TypeError: Function.prototype.apply was called on undefined, which is a undefined and not a function

  The reason is that the project does not use a standard knexfile.js. Instead, it uses custom migration scripts in src/db/migrate.js and src/db/seed.js. This is not explained anywhere, so students may spend unnecessary time debugging it.

  Suggestion: Either add a knexfile.js so the Knex CLI works, or document clearly that migrations must be created manually, including the naming convention and an example.

• 4. No guidance on creating new migrations or seeds

  The api/README.md explains how to run migrations and seeds, but not how to create them. Since Week 1 asks students to add a user table, they have to infer the structure from the existing files.

  At the moment, students have to figure out for themselves:

  which folder to use
  the timestamp-based file naming convention
  the required up() and down() exports
  that the project uses ES module syntax

  Suggestion: Add a short “Creating a new migration” section with a simple example.

• 5. Unclear where docker-compose.yml should go

  **It is not obvious whether docker-compose.yml belongs in the project root or inside api/. The .env file is in api/, but Docker Compose is usually project-level infrastructure.

  Suggestion: Pick one location and document it clearly. The root folder seems like the most natural place.

  • 6. Root README.md still focuses on MySQL

  The root README.md shows a MySQL Docker example, while the spec requires PostgreSQL. This is another point of confusion.

  Suggestion: Replace the MySQL example with PostgreSQL, or clearly state which database students should use.**

• 7. No reminder to run migrations

  The API may fail on the first request with:

  relation "event" does not exist

  This happens when npm run db:setup has not been run. The PostgreSQL error is not beginner-friendly, and the setup step is easy to miss.

  Suggestion: Add npm run db:setup to the main getting-started flow in the root README.md, before npm run dev. Even better, show a clear startup warning when migrations have not been run.

• 8. API errors return raw HTML stack traces

  When something goes wrong, the API returns a full HTML error page with a stack trace. This is difficult to read in tools like curl, and not very helpful for students.

  This is not a Week 1 blocker, but it does make debugging harder.

  Suggestion: Add a basic error-handling middleware that returns JSON error responses instead of HTML stack traces.

  Example:

  curl -s http://localhost:3001/api/users | json_pp
  curl -s http://localhost:3001/api/users/1 | json_pp

• 9. Missing auth packages in the starter code

  JWT authentication is required, but bcryptjs and jsonwebtoken are not listed in package.json. Students will get “Cannot find package” errors when they try to use them.

  Suggestion: Add them to the starter package.json, or clearly tell students to install them first with npm install bcryptjs jsonwebtoken.

• 10. JWT middleware setup is unclear

  index.mjs is locked and applies global middleware before routes. Because of that, students should not put JWT auth in the global middlewares array, or it will block public routes like /api/events and /api/auth/signup.

  The auth middleware needs to be added only to specific routes or routers, but this is not explained in the starter code. Students who do not know Express middleware order may easily make this mistake.

  Suggestion: Add a short comment or example in middlewares/index.js saying that auth middleware should be added on specific routes, not globally.

• 11. Missing JWT_SECRET in .env-template

  The .env-template does not include JWT_SECRET. If students forget to add it, jsonwebtoken.sign() will fail with a confusing error.

  Suggestion: Add JWT_SECRET=your_secret_here to .env-template and note that it is required for authentication.

• 12. No guidance for request validation

  Request validation is required, but the starter code does not include a validation library or show a clear validation example. Right now, only a simple manual check is shown.

  Students may not know whether to use manual checks or a library, and manual validation can get messy as more endpoints are added.

  Suggestion: Either add a validation library to package.json, or include a short README note explaining the recommended approach.