TimeTracker

01PS> Get-Content .\docs\problem.md

Il problema

The problem

In un team IT di consulenza, consuntivare le ore su ogni commessa è un'attività quotidiana obbligatoria, ma spesso viene gestita con strumenti non pensati per questo: fogli Excel condivisi, form SharePoint grezzi, note sparse. Il risultato è che a fine mese mancano sempre dati, si perde tempo a ricostruire cosa si è fatto e i report per il management diventano un esercizio di pazienza.

In an IT consulting team, logging hours against each project is a mandatory daily task, but it is often handled with tools not designed for it: shared Excel sheets, bare SharePoint forms, scattered notes. The result is that data is always missing at the end of the month, time is wasted reconstructing what was done, and reports for management become an exercise in patience.

Gli strumenti commerciali come Clockify o Toggl esistono, ma in contesti enterprise spesso non si possono adottare per motivi di compliance o di governance dei dati. Serviva qualcosa che girasse sull'infrastruttura Microsoft già in uso, senza dipendenze esterne e senza richiedere approvazioni IT complesse.

Commercial tools like Clockify or Toggl exist, but in enterprise contexts they often can't be adopted for compliance or data governance reasons. What was needed was something running on the Microsoft infrastructure already in use, with no external dependencies and no complex IT approvals.

02PS> Get-Content .\docs\solution.md

La soluzione

The solution

Ho costruito un'app web a singolo file HTML che si autentica tramite MSAL Browser con l'account Microsoft aziendale e salva ogni voce direttamente su una lista SharePoint Online tramite Microsoft Graph API. Nessun backend, nessun server intermedio: il browser chiama Graph API direttamente, con token OAuth 2.0 acquisito in modo silenzioso.

I built a single-file HTML web app that authenticates via MSAL Browser with the corporate Microsoft account and saves each entry directly to a SharePoint Online list through Microsoft Graph API. No backend, no intermediate server: the browser calls Graph API directly, with an OAuth 2.0 token acquired silently.

Il deploy è su Cloudflare Pages con auto-deploy da GitHub: ogni aggiornamento del file HTML viene pubblicato automaticamente in 30-60 secondi. Il fallback è localStorage: se SharePoint non è raggiungibile, l'app continua a funzionare offline e si risincronizza appena la connessione torna.

It's deployed on Cloudflare Pages with auto-deploy from GitHub: every update to the HTML file goes live automatically in 30–60 seconds. The fallback is localStorage: if SharePoint can't be reached, the app keeps working offline and resyncs as soon as the connection is back.

Come funziona

How it works

Browser (TimeTracker, singolo file HTML)
  │  [non autenticato] → login popup Microsoft
  │  [autenticato]     → token MSAL silenzioso
  ▼
MSAL Browser (Azure AD, flusso delegato)
  │  acquireTokenSilent / acquireTokenPopup
  │  scopes: Sites.ReadWrite.All · User.Read · Calendars.Read
  ▼
Microsoft Graph API
  │  GET/POST/PATCH/DELETE /sites/{site}/lists/{list}/items
  │  GET /me/calendarview  (importazione eventi Outlook)
  ▼
SharePoint Online (lista OreCommesse)
  │  cache locale ──► localStorage (fallback offline)
  ▼
Browser renderizza calendario, dashboard e report

Browser (TimeTracker, single HTML file)
  │  [not signed in] → Microsoft login popup
  │  [signed in]     → silent MSAL token
  ▼
MSAL Browser (Azure AD, delegated flow)
  │  acquireTokenSilent / acquireTokenPopup
  │  scopes: Sites.ReadWrite.All · User.Read · Calendars.Read
  ▼
Microsoft Graph API
  │  GET/POST/PATCH/DELETE /sites/{site}/lists/{list}/items
  │  GET /me/calendarview  (Outlook event import)
  ▼
SharePoint Online (OreCommesse list)
  │  local cache ──► localStorage (offline fallback)
  ▼
Browser renders calendar, dashboard and reports

Ogni voce salvata contiene: data, ore, orario di inizio e fine, commessa, attività, flag straordinario, note, nome utente ed email. Il filtro per email garantisce che ogni utente veda solo le proprie ore: più persone possono usare la stessa lista SharePoint senza interferenze.

Each saved entry contains: date, hours, start and end time, project, activity, overtime flag, notes, user name and email. Filtering by email ensures each user only sees their own hours: several people can use the same SharePoint list without interfering with each other.

03PS> Get-ChildItem .\features

Funzionalità

Features

L'app è organizzata in sezioni distinte, ognuna pensata per rispondere a un'esigenza concreta del lavoro quotidiano.

The app is organized into distinct sections, each designed for a concrete need of daily work.

04PS> Get-Content .\stack.json | ConvertFrom-Json

Stack tecnico

Tech stack

Il progetto è volutamente minimalista lato dipendenze: tutto in un singolo file HTML, senza framework né build step.

The project is deliberately minimal on dependencies: everything in a single HTML file, with no framework or build step.

// Acquisizione token silenzioso (senza popup se la sessione è attiva)// Silent token acquisition (no popup if the session is active)
const tokenResponse = await msalApp.acquireTokenSilent({
  scopes: ['Sites.ReadWrite.All', 'User.Read', 'Calendars.Read'],
  account
}).catch(() =>
  msalApp.acquireTokenPopup({ scopes, account })
);

// Lettura voci dalla lista SharePoint// Read entries from the SharePoint list
const res = await fetch(
  `https://graph.microsoft.com/v1.0/sites/${spSite}/lists/${spList}/items?$expand=fields&$filter=fields/UtenteEmail eq '${email}'`,
  { headers: { Authorization: `Bearer ${tokenResponse.accessToken}` } }
);

// Salvataggio nuova voce// Save a new entry
await fetch(
  `https://graph.microsoft.com/v1.0/sites/${spSite}/lists/${spList}/items`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${tokenResponse.accessToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      fields: { DataOre, Ore, Commessa, Attivita, Straordinario, OraInizio, OraFine, Note, Utente, UtenteEmail }
    })
  }
);

05PS> Get-History

Cosa ho imparato

What I learned

Costruire questo tool da zero, con requisiti reali e uso quotidiano da parte di un team, ha messo alla prova ogni decisione tecnica in condizioni reali. In particolare:

Building this tool from scratch, with real requirements and daily use by a team, put every technical decision to the test in real conditions. In particular:

1. Il flusso OAuth 2.0 Delegated con MSAL Browser: la differenza tra acquireTokenSilent e acquireTokenPopup, la gestione del refresh token e come evitare popup indesiderati quando la sessione è ancora valida.The delegated OAuth 2.0 flow with MSAL Browser: the difference between acquireTokenSilent and acquireTokenPopup, refresh token handling and how to avoid unwanted popups while the session is still valid.
2. Graph API per le liste SharePoint: le API REST di SharePoint tramite Graph hanno comportamenti diversi rispetto alle API Files: le colonne vanno create manualmente o via provisioning, alcuni tipi (DateTime, Boolean) richiedono formati specifici, e le colonne opzionali vanno gestite con fallback per i tenant dove non esistono.Graph API for SharePoint lists: SharePoint's REST APIs through Graph behave differently from the Files APIs: columns have to be created manually or via provisioning, some types (DateTime, Boolean) require specific formats, and optional columns need fallbacks for tenants where they don't exist.
3. Architettura offline-first con localStorage: tenere localStorage sempre sincronizzato con SharePoint (non solo in fallback) richiede di aggiornare la cache ad ogni operazione riuscita, non solo al caricamento iniziale.Offline-first architecture with localStorage: keeping localStorage always in sync with SharePoint (not only as a fallback) means updating the cache after every successful operation, not just on initial load.
4. Auto-split degli orari: l'algoritmo che divide automaticamente una voce nei slot liberi del giorno (saltando voci esistenti e la pausa pranzo virtuale) ha richiesto diversi cicli di correzione per gestire edge case come l'ordine dei blocchi, i buchi multipli e il calcolo delle ore parziali.Auto-splitting time ranges: the algorithm that automatically splits an entry into the free slots of the day (skipping existing entries and the virtual lunch break) took several rounds of fixes to handle edge cases like block order, multiple gaps and partial hours calculation.

06PS> Get-Content .\ROADMAP.md

Sviluppi futuri

What's next

Il progetto è in uso quotidiano e in continua evoluzione. Le funzionalità ancora in cantiere:

The project is in daily use and keeps evolving. Features still in the pipeline: