fix(analytics): correct hourly presence using user timezone

[Suyash-ka-github]

Description

This PR fixes incorrect hourly analytics caused by UTC-based time grouping by using the authenticated user's timezone for analytics calculations.

Previously, activity occurring during early morning hours (e.g. 4–5 AM IST) was grouped under incorrect hours due to UTC offsets. This change ensures hourly presence analytics are calculated correctly for users across different timezones.

Fixes #19

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Database migration / schema change
• Dependency update
• Performance improvement
• Test addition / improvement

Checklist

Code Quality

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings

Testing

• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I have tested the API endpoints manually (if applicable)
• I have tested with different data scenarios

Database Changes (if applicable)

• I have created a Prisma migration for any schema changes
• Migration has been tested locally
• Migration doesn't break existing data
• I have documented the migration purpose

API Changes (if applicable)

• I have documented new/modified endpoints
• I have updated request/response examples
• I have considered backward compatibility
• Error handling is implemented

Security

• I have checked for security vulnerabilities in my code
• I have not hardcoded sensitive information
• Input validation is properly implemented
• I have not introduced any new dependencies without review

Performance

• I have considered the performance impact of my changes
• I have optimized database queries (if applicable)
• I have not introduced memory leaks
• Performance-critical code has been profiled

Testing Evidence

Manual testing was performed locally:

1. Logged in with users in different timezones (Asia/Kolkata, America/New_York)
2. Generated browsing activity across multiple hours
3. Verified hourly analytics correctly reflected the user's local time
4. Confirmed early-morning UTC offset issue no longer occurs

Database Migration Details (if applicable)

API Changes (if applicable)

New Endpoints

• None

Modified Endpoints

• Login endpoint now accepts optional timezone field and stores it for analytics usage

Deprecated Endpoints

• None

Screenshots / Evidence (if applicable)

N/A (backend-only change)

Additional Notes

This change ensures analytics are globally correct for users across all timezones without introducing breaking changes. The timezone is stored once during authentication and reused for analytics calculations.

Related PRs

Related to: browseping/browser-extension#26 - This PR sends the user timezone from the browser extension that this server-side change requires. Both PRs should be merged together for complete functionality.

[Suyash-ka-github]

Hello @akash-kumar-dev This issue will be fully solved if the browser-extension PR is also merged with this so once the user logs in he can See the usage according to his time zone

[Suyash-ka-github]

Hello @akash-kumar-dev , quick nudge on this PR ...All checks are green. Let me Know if you'd like any changes, or if it's good to merge. Thanks!

[akash-kumar-dev]

Hi @Suyash-ka-github,

I appreciate your work on this. During my research, I came across the idea that handling timezone conversion on the client-side might be a better approach, as our server already uses UTC. This could simplify things, especially if a user has multiple sessions in different regions. It would also keep our server code cleaner by eliminating the need to store timezone data in the database. What are your thoughts on this alternative approach? I appreciate your current solution as well.

[Suyash-ka-github]

Hello @akash-kumar-dev so the thing is right now the live website code which is running that is doing is calculating all the analytics in the backend and sending a time bucket like this which is getting plotted

Now I will explain you what the issue can be If we handle it on the client side say the client in is New York it is 22:00(10 pm) Jan 26 in new York but the UTC time is 5 hours ahead of new your time so it is 3:00 (3 am) Jan 27 as per UTC focus on the date here so when the user clicks his Analytics tab what happens is the API call for Jan 27 is sent and as the hour bucket the response we get is only 24 hours it shows the there is no use by the user at say 5PM today but as user is still living on 26 Jan he will say that Ok But I did use it at 5PM today so the issue is API call should be made to fetch data from 05:00 Jan 26 UTC to 03:00 Jan 27 UTC which is 00:00(12 am) Jan 26 NYC to 22:00(10pm) Jan 26 NYC time if we do not tell backend that the Guy is living in new your it will only send UTC 24 hours time but the guy in New York is still living his previous day and there will be a different issue for the guy living in India as he is Ahead by 5:30 hrs so when his new day has started and he check at say 2:00 am 26th Jan IST which means 19:30 25th Jan UTC the Backend will send a Bucket Saying you have used 16:00 to 17:00 today but for him today but he has never seen 16:00 -17:00 time as it is only 2:00 am in the morning the 16:00 to 17:00 time data is from previous day. Hence I came up with that Solution. I hope you get what I am trying to say let me know if I am thinking in the right direction or if there is some other way you have in your mind
If this is still not clear We can have a Google Meet if possible.

[Suyash-ka-github]

Also there is a Mistake I did is the getHour function I forgot to update it ....The issue of calling the right query is not solved I have to Fix that so if you want to move forward with this approach let me know I have to make changes to make it work fully as now the getHour function is still in its old version creating the issue I just updated the getHourlyPresence thing. I'll make the changes if we are moving forward with this approach

[Suyash-ka-github]

Another way I can think is to make the calculation on the client side say Send me data from 5:00 Jan 26 UTC to 3:00 Jan 27 UTC so the 24 hour bucket we get is of this time only and we dont have to save the user Timezone but we have to make the calculations that from what to what time we need the analytics as per the user and according to that we have to change the backend code for time calculations I thought to make minimal changes hence I went on with this but well we can think in this direction too

[akash-kumar-dev]

Hi @Suyash-ka-github, great point—you noticed the issue around date boundaries and time range queries for analytics routes correctly. You’re right about that part. What I was trying to say is that this is the standard practice most server-side code follows, and there are established ways they handle this kind of time conflict problem.

For analytics routes, we can modify our routes and controllers to accept the timezone in the request body and process the data accordingly. However, we actually have more than just analytics routes—we also have Inbox and Last Seen features. There are already a lot of things standardized in a way that the client side can easily handle.

For analytics routes specifically, we need to handle some logic on the server side as well, in line with the previous implementation.

Now, what are your thoughts on this? Your suggestion will really help us make a better decision for the implementation.

[Suyash-ka-github]

Ok well @akash-kumar-dev I will for sure think on this and let you know what happens in the real world working software how they are handling it It would be a great opportunity to learn for me too

[Suyash-ka-github]

Hello @akash-kumar-dev I have made the changes .I saw Google analytics has an option to select time zone so Most probably they are saving it but we are going with a different approach that is once the user clicks the Analytics tab the API call is made with the users current time zone so API call is made with say Asia/Kolkata or Asia/Tokyo and as per that in the backend the data is fetched which is in UTC and then Calculated according to the users time zone and then sent to the frontend and displayed. Let me know if there is anything else I can do in it

[akash-kumar-dev]

Hi @Suyash-ka-github, the implementation looks good. I haven't fully reviewed it yet, but the approach seems good. I'm a bit busy with other work at the moment, so I'll merge it after a review on Saturday or Sunday.

[akash-kumar-dev]

If you'd like, you could also open a PR to handle timezones for "Last Seen" and "Inbox". The server currently sends this data in UTC, so it would just require handling the timezone conversion on the frontend. I don't think any server-side changes would be needed for that. What are your thoughts?

[Suyash-ka-github]

@akash-kumar-dev Sure I would love to work on that too and yes there would be no need of Server changes I will raise this issue too

[Suyash-ka-github]

Hello @akash-kumar-dev I just saw that Inbox and Last seen is already working as per the time zone could you specify about exactly what you are talking about