[U1] User Service and REST APIs by 1jeanpaul1 · Pull Request #1 · FridgeFinder/CFM_User

1jeanpaul1 · 2025-12-11T10:50:42Z

User Model and APIs

API docs: https://fridgefinder.github.io/CFM_User/

1jeanpaul1 · 2025-12-11T20:51:53Z

@@ -0,0 +1,41 @@
+name: Deploy API Docs to GitHub Pages


https://fridgefinder.github.io/CFM_User/

1jeanpaul1 · 2025-12-11T21:02:12Z

@@ -0,0 +1,22 @@
+version: "3.9"


can ignore - this is for local testing

1jeanpaul1 · 2025-12-11T21:03:05Z

@@ -0,0 +1,41 @@
+{


can ignore - for local testing

1jeanpaul1 · 2025-12-11T21:03:23Z

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3


can ignore - for local testing

1jeanpaul1 · 2025-12-11T21:32:40Z

+    return datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%S.%f')[:-3] + 'Z'
+
+
+class UserType(str, Enum):


UserTypes

Really only need Neighbor and Volunteer right now, but in the future ORGANIZER or HOST might have some special privileges

Mobile App would have to change check from isVolunteer to user.userType == 'Volunteer'

1jeanpaul1 · 2025-12-11T22:12:02Z

+    email: Optional[str] = None
+    phoneNumber: Optional[str] = None
+    zipcode: Optional[str] = None
+    fcmToken: Optional[str] = None #TODO: Consider making this a set to allow for multiple devices to receive notifications


when signing out we need to set this to None

we should also consider allowing for multiple devices to receive notifications

I think fcmToken should be a list of tokens to allow for multiple devices

1jeanpaul1 · 2025-12-11T22:17:15Z

+    }
+
+
+def error_response(status_code: int, code: ErrorCode, message: str, field: Optional[str] = None, 


API errors are returned in this format:

Status Code: 400-500
Headers: X-Request-Id - to query Cloudwatch

{ "error": { "code": "INTERNAL_ERROR_CODE", "message": "MESSAGE" } }

example:

{ "error": { "code": "FORBIDDEN", "message": "User can only update their own user data" } }

1jeanpaul1 · 2025-12-11T22:20:34Z

+        Authorizers:
+          FirebaseAuthorizer:
+            JwtConfiguration:
+              issuer: !Sub "https://securetoken.google.com/${FirebaseProjectId}"


Api Gateway Validates JWT tokens

1jeanpaul1 · 2025-12-11T22:48:43Z

User Service API Endpoints

1. Create User

POST /v1/users

Auth: Required (Firebase JWT)
Description: Create a new user account. Users are automatically assigned the Neighbor type.

Request Body:

{
  "userId": "firebase-uid-here",
  "username": "mariamekaba",
  "email": "mariame@example.com",
  "phoneNumber": "+1234567890",
  "zipcode": "12345",
  "fcmToken": "fcm-token-here",
  "settings": {
    "pushNotificationEnabled": true,
    "emailNotificationEnabled": true,
    "geofenceEnabled": false
  },
  "userType": "Neighbor"
}

Success Response (201 Created):

{
  "user": {
    "userId": "firebase-uid-here",
    ...,
    "createdAt": "2024-03-20T14:22:00.000Z",
    "lastUpdated": "2024-03-20T14:22:00.000Z",
    "lastLoginAt": "2024-03-20T14:22:00.000Z"
  }
}

2. Get User

GET /v1/users/{userId}

Auth: Required (Firebase JWT)
Description: Retrieve user profile. Users can only access their own profile.
Success Response (200 OK):

{
  "user": {
    "userId": "firebase-uid-here",
    ...
  }
}

3. Update User

PATCH /v1/users/{userId}

Auth: Required (Firebase JWT)
Description: Partially update user profile. Only provided fields will be updated.

Request Body (example - update email and settings):

{
  "email": "newemail@example.com",
  "settings": {
    "pushNotificationEnabled": false
  }
}

Success Response (200 OK):

{
  "user": {
    "userId": "firebase-uid-here",
    "email": "newemail@example.com",
    "settings": {
      "pushNotificationEnabled": false,
      "emailNotificationEnabled": true,
      "geofenceEnabled": false
    },
    "lastUpdated": "2024-03-20T15:30:00.000Z",
    ...,
  }
}

4. Delete User

DELETE /v1/users/{userId}

Auth: Required (Firebase JWT)
Description: Permanently delete user account. Users can only delete their own account.

Success Response (204 No Content):

(Empty response body)

5. Check Username Availability

GET /v1/users/check-username/{username}

Auth: Not required (Public endpoint)
Description: Check if a username is available (not taken by another user).

Success Response (200 OK) - Available:

{
  "available": true
}

Success Response (200 OK) - Taken:

{
  "available": false
}

API errors are returned in this format:

Status Code: 400-500
Headers: X-Request-Id - to query Cloudwatch

{
    "error": {
        "code": "INTERNAL_ERROR_CODE",
        "message": "MESSAGE"
    }
}

example:

{
    "error": {
        "code": "FORBIDDEN",
        "message": "User can only update their own user data"
    }
}

API Base URLs

Development: https://users-api-dev.communityfridgefinder.com

Authentication

All endpoints (except username check) require Firebase JWT in the Authorization header:

Authorization: Bearer <your-firebase-jwt-token>

Documentation

📖 Interactive API Docs: https://fridgefinder.github.io/CFM_User/

1jeanpaul1 · 2025-12-11T22:52:49Z

+          - '*'
+
+  # DynamoDB Table for Users
+  UsersTable:


Hash/PrimaryKey - userId
Indexed - username

1jeanpaul1 · 2025-12-11T22:55:04Z

+parameter_overrides = [
+  "Environment=dev",
+  "DeploymentTarget=aws",
+  "FirebaseProjectId=YOUR_STAGING_FIREBASE_PROJECT_ID",


TOOD: create firebase project on fridgefinder google account for: Dev and Prod

1jeanpaul1 · 2025-12-19T08:00:46Z

+        # Fields that can be updated (excluding userType - handled above)
+        allowed_fields = {
+            'email', 'phoneNumber', 'username', 'points',
+            'zipcode', 'fcmToken', 'lastLoginAt', 'settings'


lastLoginAt - I think there should be an api that updates this instead of the frontend sending the lastLoginAt field

1jeanpaul1 · 2026-01-24T10:54:14Z

+    GEOFENCE_ENABLED = "geofenceEnabled"
+
+
+class User(BaseModel):


Reviewer: User Model, confirm fields and structure

mansoorsiddiqui

Solid work overall, looks clean. Most of my comments are around a few edge cases and making sure we're aligned on the cross-service contract with the notification PR.

Cross-PR concerns:

EventBridge contract gap: The notification PR subscribes to "User Deleted" events from "user-service", but this PR never publishes that event. Notification cleanup won't happen on account deletion.
Error code naming: This PR uses USER_NOT_FOUND, USER_ALREADY_EXISTS while the notification PR uses NOT_FOUND, ALREADY_EXISTS. The Flutter app will need to parse errors from both — should we align on a convention?
Error response format: Both PRs use {"error": {"code": "...", "message": "..."}} which is good, but the OpenAPI spec here documents it differently. Let's make sure the specs match the implementations.

mansoorsiddiqui · 2026-02-18T21:07:42Z

+        Uses Pydantic's model_dump with enum values as strings
+        Excludes None values to save space
+        """
+        return self.model_dump(mode='json', exclude_none=True)


Quick sanity check — to_dict() uses exclude_none=True, and then update_user does a full put_item which replaces the entire DynamoDB item. So if a user clears a field (sets it to None), the old value in DynamoDB would get dropped because put_item replaces everything. Is that the intended behavior? Just want to make sure we're aligned on that.

Yes that was the intended behavior

Not sure why the API client would set any fields from not-None to None, but if it is set to None: it is recommended to not have the field at all in the db

If there are fields we don't want to go from VALUE -> NONE, we could block that as it might be a mistake? But left it open for now

mansoorsiddiqui · 2026-02-18T21:07:42Z

+  push:
+    branches:
+      - main
+      - U1_JP #TODO: remove this branch after testing


U1_JP branch is still in the trigger list with a #TODO: remove this branch after testing. Don't forget to pull this out before merging to main.

yes will remove before merging in

1jeanpaul1 · 2026-03-25T18:17:06Z

Solid work overall, looks clean. Most of my comments are around a few edge cases and making sure we're aligned on the cross-service contract with the notification PR.

Cross-PR concerns:

EventBridge contract gap: The notification PR subscribes to "User Deleted" events from "user-service", but this PR never publishes that event. Notification cleanup won't happen on account deletion.

Error code naming: This PR uses USER_NOT_FOUND, USER_ALREADY_EXISTS while the notification PR uses NOT_FOUND, ALREADY_EXISTS. The Flutter app will need to parse errors from both — should we align on a convention?

Error response format: Both PRs use {"error": {"code": "...", "message": "..."}} which is good, but the OpenAPI spec here documents it differently. Let's make sure the specs match the implementations.

Forgot to push sorry, will push User delete event
lets go with ITEM_NOT_FOUND, and ITEM_ALREADY for both
Will push fix for openAPI thank you!

1jeanpaul1 added 2 commits December 11, 2025 05:48

U1 User Service and REST APIs

89afece

U1 update workflow

bf4ba0e

FridgeFinder temporarily deployed to github-pages December 11, 2025 19:38 — with GitHub Pages Inactive

U1 update openapi examples

dc4cce1

1jeanpaul1 temporarily deployed to github-pages December 11, 2025 19:54 — with GitHub Pages Inactive

U1 update CORS and deploy-docs

267b1b4

1jeanpaul1 temporarily deployed to github-pages December 11, 2025 20:47 — with GitHub Pages Inactive

1jeanpaul1 changed the title ~~U1 User Service and REST APIs~~ [U1] User Service and REST APIs Dec 11, 2025

1jeanpaul1 commented Dec 11, 2025

View reviewed changes

Comment thread local_schema/users_dev_table.json

@@ -0,0 +1,41 @@

{

Copy link
Copy Markdown

Collaborator Author

1jeanpaul1 Dec 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can ignore - for local testing

1jeanpaul1 commented Dec 11, 2025

View reviewed changes

U1 consolidate gitignore

5aa2292

1jeanpaul1 temporarily deployed to github-pages December 11, 2025 21:06 — with GitHub Pages Inactive

1jeanpaul1 commented Dec 11, 2025

View reviewed changes

U1 small edits

56414bb

1jeanpaul1 temporarily deployed to github-pages December 11, 2025 22:39 — with GitHub Pages Inactive

1jeanpaul1 commented Dec 11, 2025

View reviewed changes

U1 add validation

bd64f7d

1jeanpaul1 temporarily deployed to github-pages December 19, 2025 07:44 — with GitHub Actions Inactive

1jeanpaul1 temporarily deployed to github-pages December 19, 2025 07:44 — with GitHub Pages Inactive

U1 fix openapi formating

3496f42

1jeanpaul1 temporarily deployed to github-pages December 19, 2025 07:46 — with GitHub Actions Inactive

1jeanpaul1 temporarily deployed to github-pages December 19, 2025 07:47 — with GitHub Pages Inactive

U1 fix openapi

bd528cb

1jeanpaul1 temporarily deployed to github-pages December 19, 2025 07:56 — with GitHub Actions Inactive

1jeanpaul1 temporarily deployed to github-pages December 19, 2025 07:56 — with GitHub Pages Inactive

1jeanpaul1 commented Dec 19, 2025

View reviewed changes

1jeanpaul1 commented Jan 24, 2026

View reviewed changes

mansoorsiddiqui reviewed Feb 18, 2026

View reviewed changes

U1 User deletion pipe

c97176e

1jeanpaul1 temporarily deployed to github-pages March 13, 2026 17:37 — with GitHub Pages Inactive

1jeanpaul1 added 8 commits March 25, 2026 15:42

U1 Update openapi with correct error response body

2c2a13a

U1 update README with testing and deployment instructions

60e8004

U1 hello world test

4904354

U1 update gitignore

5f2f592

U1 add layers for shared code, address pr comments

8de1a61

U1 add unit tests, update openapi

277ee99

U1 add internal user GET api, unit tests

380a730

U1 update interal api api gateway

5917787

1jeanpaul1 temporarily deployed to github-pages March 28, 2026 23:22 — with GitHub Actions Inactive

1jeanpaul1 temporarily deployed to github-pages March 28, 2026 23:23 — with GitHub Pages Inactive

U1 fix duplicate openapi error

1d70ea6

1jeanpaul1 temporarily deployed to github-pages March 28, 2026 23:34 — with GitHub Actions Inactive

1jeanpaul1 temporarily deployed to github-pages March 28, 2026 23:34 — with GitHub Pages Inactive

U1 add unit tests to layer functions

3c05f19

1jeanpaul1 temporarily deployed to github-pages March 29, 2026 07:27 — with GitHub Pages Inactive

U1 update error code

6a0ea46

1jeanpaul1 temporarily deployed to github-pages March 29, 2026 23:30 — with GitHub Actions Inactive

1jeanpaul1 deployed to github-pages March 29, 2026 23:30 — with GitHub Pages View deployment

		return datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%S.%f')[:-3] + 'Z'


		class UserType(str, Enum):

		}


		def error_response(status_code: int, code: ErrorCode, message: str, field: Optional[str] = None,

Conversation

1jeanpaul1 commented Dec 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

1jeanpaul1 Dec 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

1jeanpaul1 Dec 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

1jeanpaul1 commented Dec 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

User Service API Endpoints

1. Create User

2. Get User

3. Update User

4. Delete User

5. Check Username Availability

API errors are returned in this format:

API Base URLs

Authentication

Documentation

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mansoorsiddiqui left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

1jeanpaul1 commented Mar 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

1jeanpaul1 commented Dec 11, 2025 •

edited

Loading

1jeanpaul1 Dec 11, 2025 •

edited

Loading

1jeanpaul1 Dec 11, 2025 •

edited

Loading

1jeanpaul1 commented Dec 11, 2025 •

edited

Loading