TimeTracker/docs/CODEBASE_AUDIT.md

TimeTracker — Code-Grounded Audit

Date: 2026-03-16
Scope: Gaps beyond existing research (INCOMPLETE_IMPLEMENTATIONS_ANALYSIS, CLIENT_FEATURES_IMPLEMENTATION_STATUS, INVENTORY_MISSING_FEATURES). Validated against current code.

---

1. Audit Summary

Category	Finding
Backend route parity	Settings blueprint exposes /settings and /settings/preferences but templates settings/index.html and settings/preferences.html are missing; /settings is served by user_bp, so only /settings/preferences 500s when hit.
API parity	/api/search, /api/health, /api/dashboard/*, /api/activity/timeline exist. Dedicated read:inventory/write:inventory scopes added (2026-03-16); backward compatible with read:projects/write:projects.
Integrations / webhooks	GitHub and Jira webhook signature verification implemented (optional webhook_secret in Jira config; HMAC-SHA256 of body).
Client portal	Access enforced via check_client_portal_access(). Reports: date range (?days=1–365) and CSV export (?format=csv) added. Real-time (SocketIO) and dashboard preferences implemented.
Inventory	Transfers, Adjustments, Reports are in the sidebar (base.html: inventory dropdown with list_transfers, list_adjustments, reports_dashboard). Docs that said “add menu links” are stale.
Issues permissions	Non-admin filtering is implemented in issues.py via get_accessible_project_and_client_ids_for_user and query.filter(Issue.project_id.in_(...), ...).
Silent exceptions	PEPPOL (invoices.py) and activity_feed date params addressed: targeted catch, log, and optional warning or 400. Other except: pass remain in lower-impact paths.
Tests	Search API, client portal (preferences, reports, activity, SocketIO), inventory API transfers/reports, keyboard shortcuts covered. Supplier/PO web tests still missing per docs.

---

2. Detailed Gaps

2.1 Missing template: settings/preferences.html

Field	Content
Missing feature	Settings “Preferences” page template.
Evidence	app/routes/settings.py line 46: return render_template("settings/preferences.html"). Only app/templates/settings/keyboard_shortcuts.html exists; no preferences.html or index.html under settings/.
Why it matters	Any request to /settings/preferences (bookmark, doc link, or future nav) returns 500 TemplateNotFound.
Approach	Add settings/preferences.html that either redirects to user.settings (canonical user prefs) or renders a minimal page with a link to “Main settings”.
Priority	High (user-facing 500).

---

2.2 Missing template: settings/index.html

Field	Content
Missing feature	Settings hub page template.
Evidence	app/routes/settings.py line 22: return render_template("settings/index.html"). Template not present.
Why it matters	Route is only hit if something links to url_for('settings.index'). No such links found; URL /settings is taken by user_bp. So this is a latent 500 if a link is added later.
Approach	Add settings/index.html (e.g. hub with links to keyboard shortcuts and user settings) or redirect to user.settings.
Priority	Medium (latent; no current link).

---

2.3 Jira webhook: no signature verification — Fixed 2026-03-16

Field	Content
Status	Addressed. Optional webhook_secret in Jira integration config; when set, requests are verified via HMAC-SHA256 of body (headers X-Hub-Signature-256, X-Atlassian-Webhook-Signature, X-Hub-Signature).

---

2.4 API scopes: no dedicated inventory scopes — Fixed 2026-03-16

Field	Content
Status	Addressed. read:inventory and write:inventory added; inventory endpoints accept either new or legacy project scopes. See docs/api/API_TOKEN_SCOPES.md.

---

2.5 Silent exception: PEPPOL compliance check (invoices) — Fixed 2026-03-16

Field	Content
Status	Addressed. Exceptions caught and logged; generic warning “Could not verify PEPPOL compliance” shown when check fails.

---

2.6 Client portal: report export and date range — Fixed 2026-03-16

Field	Content
Status	Addressed. Reports support ?days=1–365 and ?format=csv for CSV download. PDF and saved report params remain future work.

---

2.7 Offline queue: request body and method on replay — Fixed 2026-03-16

Field	Content
Status	Addressed. Queue stores method, headers, and body in replay-safe form; replay uses them. Legacy items with options only still work via fallback.

---

2.8 Keyboard shortcuts: “Usage statistics” placeholder

Field	Content
Missing feature	Real usage data for keyboard shortcuts.
Evidence	app/templates/settings/keyboard_shortcuts.html ~286: “Usage statistics will appear here as you use keyboard shortcuts” with no backend or script feeding data.
Why it matters	UX promise with no implementation can confuse users.
Approach	Either implement simple client-side or server-side usage tracking and display, or replace copy with “Not available” / remove the section.
Priority	Low.

---

2.9 Activity feed API: broad exception swallowing — Fixed 2026-03-16

Field	Content
Status	Addressed. Date params catch ValueError only; API returns 400 for invalid dates; web route skips filter and logs.

---

3. Newly Discovered Gaps (Not in Original Research)

1. Settings templates missing
   Original docs do not mention missing settings/preferences.html and settings/index.html. These cause or would cause 500 for /settings/preferences and for any future link to the settings hub.

2. Jira webhook unauthenticated
   INCOMPLETE_IMPLEMENTATIONS_ANALYSIS only calls out GitHub webhook verification; GitHub is now implemented. Jira webhook has no signature or secret verification.

3. Inventory menu already present
   INVENTORY_MISSING_FEATURES and INVENTORY_IMPLEMENTATION_STATUS say “Add Transfers/Adjustments/Reports to menu”. In base.html the inventory dropdown already includes these links and nav_active_* for them. This is a doc staleness issue, not a code gap.

4. Issues permission filtering implemented
   Original analysis said “permission filtering for non-admin users is incomplete” in issues.py. Current issues.py uses get_accessible_project_and_client_ids_for_user and filters the query; the gap is closed.

5. Push subscription storage
   Original doc referred to “push_subscription field on User”. The app uses a PushSubscription model and persist in push_notifications.py; storage is implemented.

6. Offline task/project sync implemented
   Original doc said “TODO: Implement task sync” and “project sync” in offline-sync.js. offline-sync.js contains full syncTasks() and syncProjects() with fetch to /api/v1/tasks and /api/v1/projects. The gap is closed; docs are stale.

7. Search API implemented
   /api/search exists in app/routes/api.py and is tested; frontend uses it. No missing search endpoint.

8. Client portal report scoping
   Reports are built from get_portal_data(client) and build_report_data(client, ...); no cross-client data leak found. Real gap is export and date range (see 2.6).

9. No dedicated inventory API scopes
   Not called out in original research; discovered via API_TOKEN_SCOPES and api_auth.

10. Keyboard shortcuts “usage statistics”
    Placeholder UI with no backend; not in original list.

---

4. Roadmap

Quick wins

• Add settings/preferences.html so /settings/preferences does not 500 (redirect or minimal page with link to main settings).
• Add settings/index.html (hub or redirect to user.settings) to avoid future 500.
• Replace invoices.py PEPPOL except Exception: pass with targeted catch + log (and optional generic warning).

Medium effort / high impact

• Jira webhook verification: Add shared-secret or signature check from headers; document in integration config.
• Client report export: Add CSV (and optionally PDF) export and optional date range params for client portal reports.
• Inventory API scopes: Introduce read:inventory / write:inventory and gate inventory endpoints; keep project-scope fallback for backward compatibility.
• Activity feed date params: Validate date query params and return 400 on invalid input instead of silent pass.

Architectural improvements

• Centralized exception handling: Replace high-impact except: pass with a small set of helpers (e.g. safe_log, structured error response) and use them in routes/api.
• Offline queue robustness: Standardize how request body/method are stored and replayed; add tests for offline POST replay.
• Docs and status sync: Update INVENTORY_MISSING_FEATURES / INVENTORY_IMPLEMENTATION_STATUS to reflect current menu and API; add a short “verified on <date>” note to INCOMPLETE_IMPLEMENTATIONS_ANALYSIS for items now fixed (GitHub webhook, issues permissions, search API, push storage, offline sync).

---

5. Implemented Quick Wins and Audit Gaps

1. /settings/preferences no longer 500s
   The route now redirects to user.settings with an info flash (“Your preferences are managed on the main Settings page”) instead of rendering a missing template.

2. /settings (settings index) no longer 500s
   The settings hub route now redirects to user.settings. (In practice /settings is already served by user_bp since it is registered first; this change makes the settings blueprint safe if registration order changes or anything links to settings.index.)

Implemented 2026-03-16 (audit gaps)

3. Jira webhook verification — Optional webhook_secret in Jira integration; when set, incoming webhooks are verified via HMAC-SHA256 of the request body.
4. Exception handling (invoices, activity_feed) — PEPPOL block: targeted catch, log, generic warning. Activity feed API: invalid start_date/end_date return 400; web route skips filter and logs.
5. Client portal reports — Date range ?days=1–365 and CSV export ?format=csv.
6. Inventory API scopes — read:inventory and write:inventory added; backward compatible with read:projects/write:projects.
7. Offline queue replay — Request body and method stored and replayed correctly for POST/PUT.

---

Last updated: 2026-03-16