From 9853c7dd320192be26cd1c218b762e3031d5dab8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Carlos=20Sans=C3=B3n?=
 <57395395+csansoon@users.noreply.github.com>
Date: Thu, 26 Sep 2024 10:40:00 +0200
Subject: [PATCH] Usage Indicator (#278)

---
 apps/web/src/actions/workspaces/usage.ts      |  11 +
 .../AppLayout/Header/UsageIndicator/index.tsx | 160 +++++++++
 .../layouts/AppLayout/Header/index.tsx        |   4 +-
 apps/web/src/stores/workspaceUsage.ts         |  53 +++
 apps/websockets/src/server.ts                 |   5 +
 packages/core/src/constants.ts                |   7 +
 .../events/handlers/documentLogs/createJob.ts |  18 +-
 .../core/src/services/documentLogs/create.ts  |   3 +
 .../core/src/services/workspaces/create.ts    |   4 +-
 .../core/src/services/workspaces/index.ts     |   1 +
 .../src/services/workspaces/usage.test.ts     | 319 ++++++++++++++++++
 .../core/src/services/workspaces/usage.ts     |  61 ++++
 .../core/src/tests/factories/documentLogs.ts  |   3 +
 .../core/src/tests/factories/workspaces.ts    |   2 +
 packages/core/src/websockets/constants.ts     |  13 +
 .../src/ds/atoms/CircularProgress/index.tsx   |  80 +++++
 packages/web-ui/src/ds/atoms/index.ts         |   1 +
 17 files changed, 741 insertions(+), 4 deletions(-)
 create mode 100644 apps/web/src/actions/workspaces/usage.ts
 create mode 100644 apps/web/src/components/layouts/AppLayout/Header/UsageIndicator/index.tsx
 create mode 100644 apps/web/src/stores/workspaceUsage.ts
 create mode 100644 packages/core/src/services/workspaces/usage.test.ts
 create mode 100644 packages/core/src/services/workspaces/usage.ts
 create mode 100644 packages/web-ui/src/ds/atoms/CircularProgress/index.tsx

diff --git a/apps/web/src/actions/workspaces/usage.ts b/apps/web/src/actions/workspaces/usage.ts
new file mode 100644
index 000000000..1c3463e25
--- /dev/null
+++ b/apps/web/src/actions/workspaces/usage.ts
@@ -0,0 +1,11 @@
+'use server'
+
+import { computeWorkspaceUsage } from '@latitude-data/core/services/workspaces/usage'
+
+import { authProcedure } from '../procedures'
+
+export const fetchWorkspaceUsageAction = authProcedure
+  .createServerAction()
+  .handler(async ({ ctx }) => {
+    return await computeWorkspaceUsage(ctx.workspace).then((r) => r.unwrap())
+  })
diff --git a/apps/web/src/components/layouts/AppLayout/Header/UsageIndicator/index.tsx b/apps/web/src/components/layouts/AppLayout/Header/UsageIndicator/index.tsx
new file mode 100644
index 000000000..1e1103825
--- /dev/null
+++ b/apps/web/src/components/layouts/AppLayout/Header/UsageIndicator/index.tsx
@@ -0,0 +1,160 @@
+'use client'
+
+import { ReactNode, useMemo } from 'react'
+
+import { WorkspaceUsage } from '@latitude-data/core/browser'
+import {
+  Badge,
+  Button,
+  CircularProgress,
+  CircularProgressProps,
+  Skeleton,
+  Text,
+} from '@latitude-data/web-ui'
+import useWorkspaceUsage from '$/stores/workspaceUsage'
+import Link from 'next/link'
+import Popover from 'node_modules/@latitude-data/web-ui/src/ds/atoms/Popover'
+
+function UsageIndicatorCircle({
+  data,
+  isLoading,
+  ...props
+}: Omit<CircularProgressProps, 'value' | 'color'> & {
+  data: WorkspaceUsage | undefined
+  isLoading: boolean
+}) {
+  const ratio = useMemo(() => {
+    if (!data) return 0
+    if (data.max === 0) return 0
+    const actualRatio = (data.max - data.usage) / data.max
+
+    if (actualRatio <= 0) return 0
+    if (actualRatio >= 1) return 1
+
+    if (actualRatio < 0.01) return 0.01 // Too low of a ratio makes the circle so small it disappears
+    return actualRatio
+  }, [data])
+
+  if (isLoading) {
+    return (
+      <CircularProgress
+        value={1}
+        color='foregroundMuted'
+        className='opacity-25 animate-pulse'
+        animateOnMount={false}
+        {...props}
+      />
+    )
+  }
+  if (ratio <= 0) {
+    return <CircularProgress value={1} color='destructive' {...props} />
+  }
+
+  return (
+    <CircularProgress
+      value={ratio || 1}
+      color={
+        ratio > 0.25
+          ? 'primary'
+          : ratio === 0
+            ? 'destructive'
+            : 'warningMutedForeground'
+      }
+      {...props}
+    />
+  )
+}
+
+function LoadingText({
+  isLoading,
+  children,
+}: {
+  isLoading: boolean
+  children: ReactNode
+}) {
+  if (isLoading) {
+    return <Skeleton className='w-20 h-4 animate-pulse' />
+  }
+
+  return children
+}
+
+function descriptionText({ usage, max }: WorkspaceUsage) {
+  const ratio = (max - usage) / max
+
+  if (ratio <= 0) {
+    return "You've reached the maximum number of runs. Your app will continue working, the Latitude limit reached means you'll no longer be able to run tests, view new logs or evaluation results."
+  }
+  if (ratio < 0.25) {
+    return "You're running low on runs in your current plan. Your app will continue working, the Latitude limit reached means you'll no longer be able to run tests, view new logs or evaluation results."
+  }
+
+  return `Your plan has included ${max} runs. You can upgrade your plan to get more runs.`
+}
+
+export function UsageIndicator() {
+  const { data, isLoading } = useWorkspaceUsage()
+
+  return (
+    <Popover.Root>
+      <Popover.Trigger asChild>
+        <Button variant='ghost' className='hover:bg-muted'>
+          <div className='flex flex-row items-center gap-x-2'>
+            <UsageIndicatorCircle data={data} isLoading={isLoading} />
+            <LoadingText isLoading={isLoading}>
+              <Text.H6>
+                {data?.usage} / {data?.max}
+              </Text.H6>
+            </LoadingText>
+          </div>
+        </Button>
+      </Popover.Trigger>
+      <Popover.Content
+        side='bottom'
+        sideOffset={8}
+        align='center'
+        className='bg-background rounded-md w-80 p-4 shadow-lg border border-border'
+      >
+        <div className='flex flex-col gap-4'>
+          <div className='flex flex-row items-center gap-2'>
+            <UsageIndicatorCircle
+              data={data}
+              size={20}
+              isLoading={isLoading}
+              backgroundColor='foregroundMuted'
+              className='overflow-clip'
+            />
+            <LoadingText isLoading={isLoading}>
+              <div className='flex flex-row w-full items-center gap-2'>
+                <Text.H4 color='foreground'>{data?.usage}</Text.H4>
+                <Text.H4 color='foregroundMuted' noWrap>
+                  {' '}
+                  / {data?.max} runs
+                </Text.H4>
+                <div className='w-full flex items-center justify-end'>
+                  <Badge variant='muted'>
+                    <Text.H6 color='foregroundMuted'>Team Plan</Text.H6>
+                  </Badge>
+                </div>
+              </div>
+            </LoadingText>
+          </div>
+          {data ? (
+            <Text.H6>{descriptionText(data)}</Text.H6>
+          ) : (
+            <div className='w-full flex flex-col gap-1'>
+              <Skeleton className='w-full h-3 animate-pulse' />
+              <Skeleton className='w-full h-3 animate-pulse' />
+              <Skeleton className='w-[40%] h-3 animate-pulse' />
+            </div>
+          )}
+          <div className='flex flex-row'>
+            <Link href='mailto:hello@latitude.so'>
+              <Button fancy>Contact us to upgrade</Button>
+            </Link>
+          </div>
+        </div>
+      </Popover.Content>
+    </Popover.Root>
+  )
+}
diff --git a/apps/web/src/components/layouts/AppLayout/Header/index.tsx b/apps/web/src/components/layouts/AppLayout/Header/index.tsx
index 61bcf3f40..eb2310276 100644
--- a/apps/web/src/components/layouts/AppLayout/Header/index.tsx
+++ b/apps/web/src/components/layouts/AppLayout/Header/index.tsx
@@ -10,6 +10,7 @@ import Link from 'next/link'
 import { Fragment } from 'react/jsx-runtime'
 
 import AvatarDropdown from './AvatarDropdown'
+import { UsageIndicator } from './UsageIndicator'
 
 function BreadcrumbSeparator() {
   return (
@@ -110,7 +111,8 @@ export default function AppHeader({
       <div className='py-3 flex flex-row items-center justify-between'>
         <Breadcrumb showLogo breadcrumbs={breadcrumbs} />
         <div className='flex flex-row items-center gap-x-6'>
-          <nav className='flex flex-row gap-x-4'>
+          <nav className='flex flex-row gap-x-4 items-center'>
+            <UsageIndicator />
             {navigationLinks.map((link, idx) => (
               <NavLink key={idx} {...link} />
             ))}
diff --git a/apps/web/src/stores/workspaceUsage.ts b/apps/web/src/stores/workspaceUsage.ts
new file mode 100644
index 000000000..a2e38f342
--- /dev/null
+++ b/apps/web/src/stores/workspaceUsage.ts
@@ -0,0 +1,53 @@
+import { useCallback } from 'react'
+
+import { WorkspaceUsage } from '@latitude-data/core/browser'
+import { useToast } from '@latitude-data/web-ui'
+import { fetchWorkspaceUsageAction } from '$/actions/workspaces/usage'
+import { useSockets } from '$/components/Providers/WebsocketsProvider/useSockets'
+import useSWR, { SWRConfiguration } from 'swr'
+
+export default function useWorkspaceUsage(opts?: SWRConfiguration) {
+  const { toast } = useToast()
+  const {
+    mutate,
+    data = undefined,
+    isLoading,
+    error: swrError,
+  } = useSWR<WorkspaceUsage | undefined>(
+    ['workspaceUsage'],
+    useCallback(async () => {
+      const [data, error] = await fetchWorkspaceUsageAction()
+      if (error) {
+        toast({
+          title: 'Error',
+          description: error.message,
+          variant: 'destructive',
+        })
+      }
+      if (!data) return undefined
+
+      return data
+    }, []),
+    opts,
+  )
+
+  const onMessage = useCallback(() => {
+    mutate(
+      (prevData) => {
+        if (!prevData) return prevData
+        return {
+          ...prevData,
+          usage: prevData.usage + 1,
+        }
+      },
+      {
+        revalidate: false,
+      },
+    )
+  }, [])
+
+  useSockets({ event: 'evaluationResultCreated', onMessage })
+  useSockets({ event: 'documentLogCreated', onMessage })
+
+  return { data, mutate, isLoading, error: swrError }
+}
diff --git a/apps/websockets/src/server.ts b/apps/websockets/src/server.ts
index 1875d4855..8a3ab9f9b 100644
--- a/apps/websockets/src/server.ts
+++ b/apps/websockets/src/server.ts
@@ -136,6 +136,11 @@ workers.on('connection', (socket) => {
     const workspace = buildWorkspaceRoom({ workspaceId })
     web.to(workspace).emit('evaluationResultCreated', data)
   })
+  socket.on('documentLogCreated', (args) => {
+    const { workspaceId, data } = args
+    const workspace = buildWorkspaceRoom({ workspaceId })
+    web.to(workspace).emit('documentLogCreated', data)
+  })
 })
 
 const PORT = process.env.WEBSOCKETS_SERVER_PORT || 4002
diff --git a/packages/core/src/constants.ts b/packages/core/src/constants.ts
index 5041e2011..54d1c8f66 100644
--- a/packages/core/src/constants.ts
+++ b/packages/core/src/constants.ts
@@ -19,6 +19,8 @@ export const LATITUDE_SLACK_URL =
   'https://trylatitude.slack.com/join/shared_invite/zt-17dyj4elt-rwM~h2OorAA3NtgmibhnLA#/shared-invite/email'
 export const LATITUDE_HELP_URL = LATITUDE_SLACK_URL
 export const HEAD_COMMIT = 'live'
+export const MAX_FREE_RUNS = 50_000
+
 export enum CommitStatus {
   All = 'all',
   Merged = 'merged',
@@ -155,6 +157,11 @@ export type EvaluationMeanValue = {
   meanValue: number
 }
 
+export type WorkspaceUsage = {
+  usage: number
+  max: number
+}
+
 export type ChainCallResponseDto = Omit<
   ChainCallResponse,
   'documentLogUuid' | 'providerLog'
diff --git a/packages/core/src/events/handlers/documentLogs/createJob.ts b/packages/core/src/events/handlers/documentLogs/createJob.ts
index 1a50456c2..4499c7659 100644
--- a/packages/core/src/events/handlers/documentLogs/createJob.ts
+++ b/packages/core/src/events/handlers/documentLogs/createJob.ts
@@ -4,6 +4,7 @@ import {
   createDocumentLog,
   CreateDocumentLogProps,
 } from '../../../services/documentLogs'
+import { WebsocketClient } from '../../../websockets/workers'
 
 export type CreateDocumentLogJobData = CreateDocumentLogProps
 
@@ -12,7 +13,9 @@ export const createDocumentLogJob = async ({
 }: {
   data: DocumentRunEvent
 }) => {
-  const scope = new CommitsRepository(event.data.workspaceId)
+  const websockets = await WebsocketClient.getSocket()
+  const workspaceId = event.data.workspaceId
+  const scope = new CommitsRepository(workspaceId)
   const commit = await scope
     .getCommitByUuid({
       projectId: event.data.projectId,
@@ -20,7 +23,7 @@ export const createDocumentLogJob = async ({
     })
     .then((r) => r.unwrap())
 
-  await createDocumentLog({
+  const documentLog = await createDocumentLog({
     commit,
     data: {
       customIdentifier: event.data.customIdentifier,
@@ -32,4 +35,15 @@ export const createDocumentLogJob = async ({
       source: event.data.source,
     },
   }).then((r) => r.unwrap())
+
+  // TODO: Move to its own event handler.
+  websockets.emit('documentLogCreated', {
+    workspaceId,
+    data: {
+      workspaceId,
+      documentUuid: event.data.documentUuid,
+      commitUuid: event.data.commitUuid,
+      documentLogId: documentLog.id,
+    },
+  })
 }
diff --git a/packages/core/src/services/documentLogs/create.ts b/packages/core/src/services/documentLogs/create.ts
index 3b043aa56..d668d684e 100644
--- a/packages/core/src/services/documentLogs/create.ts
+++ b/packages/core/src/services/documentLogs/create.ts
@@ -14,6 +14,7 @@ export type CreateDocumentLogProps = {
     customIdentifier?: string
     duration: number
     source: LogSources
+    createdAt?: Date
   }
 }
 
@@ -27,6 +28,7 @@ export async function createDocumentLog(
       customIdentifier,
       duration,
       source,
+      createdAt,
     },
     commit,
   }: CreateDocumentLogProps,
@@ -44,6 +46,7 @@ export async function createDocumentLog(
         customIdentifier,
         duration,
         source,
+        createdAt,
       })
       .returning()
 
diff --git a/packages/core/src/services/workspaces/create.ts b/packages/core/src/services/workspaces/create.ts
index 5064dbe94..f9e9f0c73 100644
--- a/packages/core/src/services/workspaces/create.ts
+++ b/packages/core/src/services/workspaces/create.ts
@@ -8,16 +8,18 @@ export async function createWorkspace(
   {
     name,
     user,
+    createdAt,
   }: {
     name: string
     user: User
+    createdAt?: Date
   },
   db = database,
 ) {
   return Transaction.call<Workspace>(async (tx) => {
     const insertedWorkspaces = await tx
       .insert(workspaces)
-      .values({ name, creatorId: user.id })
+      .values({ name, creatorId: user.id, createdAt })
       .returning()
     const workspace = insertedWorkspaces[0]!
 
diff --git a/packages/core/src/services/workspaces/index.ts b/packages/core/src/services/workspaces/index.ts
index c40e132f3..8fd676a1e 100644
--- a/packages/core/src/services/workspaces/index.ts
+++ b/packages/core/src/services/workspaces/index.ts
@@ -1,2 +1,3 @@
 export * from './create'
 export * from './update'
+export * from './usage'
diff --git a/packages/core/src/services/workspaces/usage.test.ts b/packages/core/src/services/workspaces/usage.test.ts
new file mode 100644
index 000000000..aa350097b
--- /dev/null
+++ b/packages/core/src/services/workspaces/usage.test.ts
@@ -0,0 +1,319 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { DocumentLog } from '../../browser'
+import { Providers } from '../../constants'
+import { connectEvaluations } from '../evaluations'
+import { computeWorkspaceUsage, getLatestRenewalDate } from './usage'
+
+describe('computeWorkspaceUsage', () => {
+  it('calculates usage correctly when there are evaluation results and document logs', async (ctx) => {
+    const { workspace, commit, documents, evaluations } =
+      await ctx.factories.createProject({
+        providers: [{ type: Providers.OpenAI, name: 'test' }],
+        documents: {
+          foo: ctx.factories.helpers.createPrompt({ provider: 'test' }),
+        },
+        evaluations: [
+          { prompt: ctx.factories.helpers.createPrompt({ provider: 'test' }) },
+        ],
+      })
+
+    const NUM_DOC_LOGS = 5
+    const NUM_EVAL_LOGS = 5
+
+    const document = documents[0]!
+    const evaluation = evaluations[0]!
+    await connectEvaluations({
+      workspace,
+      documentUuid: document.documentUuid,
+      evaluationUuids: [evaluation.uuid],
+    })
+
+    // Create document logs
+    const documentLogs: DocumentLog[] = await Promise.all(
+      Array(NUM_DOC_LOGS)
+        .fill(null)
+        .map(() =>
+          ctx.factories
+            .createDocumentLog({
+              document,
+              commit,
+            })
+            .then((r) => r.documentLog),
+        ),
+    )
+
+    const evaluationLogs = await Promise.all(
+      Array(NUM_EVAL_LOGS)
+        .fill(null)
+        .map((_, idx) =>
+          ctx.factories
+            .createEvaluationResult({
+              documentLog: documentLogs[idx % documentLogs.length]!,
+              evaluation,
+            })
+            .then((r) => r.evaluationResult),
+        ),
+    )
+
+    const result = await computeWorkspaceUsage(workspace).then((r) =>
+      r.unwrap(),
+    )
+
+    expect(result.usage).toBe(documentLogs.length + evaluationLogs.length)
+  })
+
+  it('calculates usage correctly when there are no evaluation results or document logs', async (ctx) => {
+    const { workspace, documents, evaluations } =
+      await ctx.factories.createProject({
+        providers: [{ type: Providers.OpenAI, name: 'test' }],
+        documents: {
+          foo: ctx.factories.helpers.createPrompt({ provider: 'test' }),
+        },
+        evaluations: [
+          { prompt: ctx.factories.helpers.createPrompt({ provider: 'test' }) },
+        ],
+      })
+
+    const document = documents[0]!
+    const evaluation = evaluations[0]!
+    await connectEvaluations({
+      workspace,
+      documentUuid: document.documentUuid,
+      evaluationUuids: [evaluation.uuid],
+    })
+
+    const result = await computeWorkspaceUsage(workspace).then((r) =>
+      r.unwrap(),
+    )
+
+    expect(result.usage).toBe(0)
+  })
+
+  it('calculates usage correctly across multiple projects within the workspace', async (ctx) => {
+    const {
+      workspace,
+      commit: commit1,
+      documents: documents1,
+      evaluations,
+    } = await ctx.factories.createProject({
+      providers: [{ type: Providers.OpenAI, name: 'test' }],
+      documents: {
+        foo: ctx.factories.helpers.createPrompt({ provider: 'test' }),
+      },
+      evaluations: [
+        { prompt: ctx.factories.helpers.createPrompt({ provider: 'test' }) },
+      ],
+    })
+
+    const { commit: commit2, documents: documents2 } =
+      await ctx.factories.createProject({
+        workspace,
+        documents: {
+          bar: ctx.factories.helpers.createPrompt({ provider: 'test' }),
+        },
+      })
+
+    const NUM_DOC_LOGS_PER_PROJECT = 5
+    const NUM_EVAL_LOGS_PER_PROJECT = 5
+
+    const evaluation = evaluations[0]!
+    const document1 = documents1[0]!
+    const document2 = documents2[0]!
+
+    await connectEvaluations({
+      workspace,
+      documentUuid: document1.documentUuid,
+      evaluationUuids: [evaluation.uuid],
+    })
+
+    await connectEvaluations({
+      workspace,
+      documentUuid: document2.documentUuid,
+      evaluationUuids: [evaluation.uuid],
+    })
+
+    const document1Logs: DocumentLog[] = await Promise.all(
+      Array(NUM_DOC_LOGS_PER_PROJECT)
+        .fill(null)
+        .map(() =>
+          ctx.factories
+            .createDocumentLog({
+              document: document1,
+              commit: commit1,
+            })
+            .then((r) => r.documentLog),
+        ),
+    )
+
+    const document2Logs: DocumentLog[] = await Promise.all(
+      Array(NUM_DOC_LOGS_PER_PROJECT)
+        .fill(null)
+        .map(() =>
+          ctx.factories
+            .createDocumentLog({
+              document: document2,
+              commit: commit2,
+            })
+            .then((r) => r.documentLog),
+        ),
+    )
+
+    const evaluation1Logs = await Promise.all(
+      Array(NUM_EVAL_LOGS_PER_PROJECT)
+        .fill(null)
+        .map((_, idx) =>
+          ctx.factories
+            .createEvaluationResult({
+              documentLog: document1Logs[idx % document1Logs.length]!,
+              evaluation,
+            })
+            .then((r) => r.evaluationResult),
+        ),
+    )
+
+    const evaluation2Logs = await Promise.all(
+      Array(NUM_EVAL_LOGS_PER_PROJECT)
+        .fill(null)
+        .map((_, idx) =>
+          ctx.factories
+            .createEvaluationResult({
+              documentLog: document2Logs[idx % document2Logs.length]!,
+              evaluation,
+            })
+            .then((r) => r.evaluationResult),
+        ),
+    )
+
+    const documentLogs = [...document1Logs, ...document2Logs]
+    const evaluationLogs = [...evaluation1Logs, ...evaluation2Logs]
+
+    const result = await computeWorkspaceUsage(workspace).then((r) =>
+      r.unwrap(),
+    )
+
+    expect(result.usage).toBe(documentLogs.length + evaluationLogs.length)
+  })
+
+  it('only takes into account the runs since the last renewal', async (ctx) => {
+    const today = new Date(2024, 9, 12)
+    const createdAt = new Date(2023, 6, 3)
+    vi.spyOn(Date, 'now').mockImplementation(() => today.getTime())
+
+    const { workspace, commit, documents } = await ctx.factories.createProject({
+      providers: [{ type: Providers.OpenAI, name: 'test' }],
+      documents: {
+        foo: ctx.factories.helpers.createPrompt({ provider: 'test' }),
+      },
+      workspace: {
+        createdAt,
+      },
+    })
+
+    expect(workspace.createdAt).toEqual(createdAt)
+    const document = documents[0]!
+
+    const NUM_NOT_INCLUDED_DOC_LOGS = 5
+    const NUM_INCLUDED_DOC_LOGS = 5
+
+    // Workspace was created on 2023-06-03
+    // Today is 2024-09-12, which means the last monthly renewal should be on 2024-09-12
+    const expectedLastRenewalDate = new Date(2024, 9, 12)
+
+    await Promise.all(
+      Array(NUM_NOT_INCLUDED_DOC_LOGS)
+        .fill(null)
+        .map((idx) => {
+          const dateBeforeLastRenewal = new Date(
+            createdAt.getTime() +
+              (expectedLastRenewalDate.getTime() - createdAt.getTime()) *
+                (idx / (NUM_NOT_INCLUDED_DOC_LOGS - 1)),
+          )
+          return ctx.factories.createDocumentLog({
+            document,
+            commit,
+            createdAt: dateBeforeLastRenewal,
+          })
+        }),
+    )
+
+    await Promise.all(
+      Array(NUM_INCLUDED_DOC_LOGS)
+        .fill(null)
+        .map((idx) => {
+          const dateAfterLastRenewal = new Date(
+            expectedLastRenewalDate.getTime() +
+              (today.getTime() - expectedLastRenewalDate.getTime()) *
+                (idx / (NUM_INCLUDED_DOC_LOGS - 1)),
+          )
+          return ctx.factories.createDocumentLog({
+            document,
+            commit,
+            createdAt: dateAfterLastRenewal,
+          })
+        }),
+    )
+
+    const result = await computeWorkspaceUsage(workspace).then((r) =>
+      r.unwrap(),
+    )
+
+    expect(result.usage).toBe(NUM_INCLUDED_DOC_LOGS)
+  })
+})
+
+describe('getLatestRenewalDate', () => {
+  it('returns the first renewal date if the target date is before the first renewal date', () => {
+    const firstRenewalDate = new Date(2000, 9, 12)
+    const targetDate = new Date(1980, 1, 1)
+
+    const result = getLatestRenewalDate(firstRenewalDate, targetDate)
+
+    expect(result).toEqual(firstRenewalDate)
+  })
+
+  it('returns the original date if a month has not yet passed', () => {
+    const firstRenewalDate = new Date(2024, 9, 12)
+    const targetDate = new Date(2024, 9, 15)
+
+    const result = getLatestRenewalDate(firstRenewalDate, targetDate)
+
+    expect(result).toEqual(firstRenewalDate)
+  })
+
+  it('returns the same month as the target when the target day number is greater', () => {
+    const firstRenewalDate = new Date(2000, 2, 12)
+    const targetDate = new Date(2024, 5, 15)
+
+    const result = getLatestRenewalDate(firstRenewalDate, targetDate)
+
+    expect(result).toEqual(new Date(2024, 5, 12))
+  })
+
+  it('returns the previous month as the target when the target day number is lesser', () => {
+    const firstRenewalDate = new Date(2000, 2, 12)
+    const targetDate = new Date(2024, 5, 10)
+
+    const result = getLatestRenewalDate(firstRenewalDate, targetDate)
+
+    expect(result).toEqual(new Date(2024, 4, 12))
+  })
+
+  it('returns the same date as the target when the target day number is equal', () => {
+    const firstRenewalDate = new Date(2000, 2, 12)
+    const targetDate = new Date(2024, 5, 12)
+
+    const result = getLatestRenewalDate(firstRenewalDate, targetDate)
+
+    expect(result).toEqual(new Date(2024, 5, 12))
+  })
+
+  it('returns the previous December when the target date is in January', () => {
+    const firstRenewalDate = new Date(2000, 2, 12)
+    const targetDate = new Date(2024, 0, 1) // 0 = January
+
+    const result = getLatestRenewalDate(firstRenewalDate, targetDate)
+
+    expect(result).toEqual(new Date(2023, 11, 12))
+  })
+})
diff --git a/packages/core/src/services/workspaces/usage.ts b/packages/core/src/services/workspaces/usage.ts
new file mode 100644
index 000000000..19e8a0d94
--- /dev/null
+++ b/packages/core/src/services/workspaces/usage.ts
@@ -0,0 +1,61 @@
+import { count, gte } from 'drizzle-orm'
+
+import { MAX_FREE_RUNS, Workspace, WorkspaceUsage } from '../../browser'
+import { database } from '../../client'
+import { PromisedResult, Result } from '../../lib'
+import { EvaluationResultsRepository } from '../../repositories'
+import { DocumentLogsRepository } from '../../repositories/documentLogsRepository'
+
+export function getLatestRenewalDate(firstRenewalDate: Date, targetDate: Date) {
+  if (targetDate.getTime() < firstRenewalDate.getTime()) {
+    return firstRenewalDate
+  }
+
+  const day = firstRenewalDate.getDate() // The day of the month is always mantained.
+
+  return new Date(
+    targetDate.getFullYear(),
+    (targetDate.getMonth() - (targetDate.getDate() < day ? 1 : 0)) % 12,
+    day,
+  )
+}
+
+export async function computeWorkspaceUsage(
+  workspace: Workspace,
+  db = database,
+): PromisedResult<WorkspaceUsage> {
+  const { scope: documentLogsScope } = new DocumentLogsRepository(
+    workspace.id,
+    db,
+  )
+  const { scope: evaluationResultsScope } = new EvaluationResultsRepository(
+    workspace.id,
+    db,
+  )
+
+  const createdAtDate = workspace.createdAt
+  const currentDate = new Date(Date.now())
+
+  const latestRenewalDate = getLatestRenewalDate(createdAtDate, currentDate)
+
+  const evaluationResultsCount = await db
+    .select({
+      count: count(evaluationResultsScope.id),
+    })
+    .from(evaluationResultsScope)
+    .where(gte(evaluationResultsScope.createdAt, latestRenewalDate))
+    .then((r) => r[0]?.count ?? 0)
+
+  const documentLogsCount = await db
+    .select({
+      count: count(documentLogsScope.id),
+    })
+    .from(documentLogsScope)
+    .where(gte(documentLogsScope.createdAt, latestRenewalDate))
+    .then((r) => r[0]?.count ?? 0)
+
+  return Result.ok({
+    usage: evaluationResultsCount + documentLogsCount,
+    max: MAX_FREE_RUNS,
+  })
+}
diff --git a/packages/core/src/tests/factories/documentLogs.ts b/packages/core/src/tests/factories/documentLogs.ts
index a8b6f128a..27685967f 100644
--- a/packages/core/src/tests/factories/documentLogs.ts
+++ b/packages/core/src/tests/factories/documentLogs.ts
@@ -15,6 +15,7 @@ export type IDocumentLogData = {
   commit: Commit
   parameters?: Record<string, unknown>
   customIdentifier?: string
+  createdAt?: Date
 }
 
 export async function createDocumentLog({
@@ -22,6 +23,7 @@ export async function createDocumentLog({
   commit,
   parameters,
   customIdentifier,
+  createdAt,
 }: IDocumentLogData) {
   const workspace = (await findWorkspaceFromCommit(commit))!
   const providerScope = new ProviderApiKeysRepository(workspace.id)
@@ -98,6 +100,7 @@ export async function createDocumentLog({
       customIdentifier,
       source: LogSources.API,
       duration,
+      createdAt,
     },
   }).then((r) => r.unwrap())
 
diff --git a/packages/core/src/tests/factories/workspaces.ts b/packages/core/src/tests/factories/workspaces.ts
index 09ad947d6..df5abfccd 100644
--- a/packages/core/src/tests/factories/workspaces.ts
+++ b/packages/core/src/tests/factories/workspaces.ts
@@ -8,6 +8,7 @@ import { createUser, type ICreateUser } from './users'
 export type ICreateWorkspace = {
   name?: string
   creator?: User | ICreateUser
+  createdAt?: Date
 }
 export async function createWorkspace(
   workspaceData: Partial<ICreateWorkspace> = {},
@@ -22,6 +23,7 @@ export async function createWorkspace(
   const result = await createWorkspaceFn({
     name: name ?? randomName,
     user: userData,
+    createdAt: workspaceData.createdAt,
   })
   const workspace = result.unwrap()
   await createMembership({ workspace, user: userData }).then((r) => r.unwrap())
diff --git a/packages/core/src/websockets/constants.ts b/packages/core/src/websockets/constants.ts
index c739ed3c0..d8dd71cbc 100644
--- a/packages/core/src/websockets/constants.ts
+++ b/packages/core/src/websockets/constants.ts
@@ -46,11 +46,20 @@ type evaluationResultCreatedArgs = {
   row: EvaluationResultWithMetadata
 }
 
+type DocumentLogCreatedArgs = {
+  workspaceId: number
+  documentUuid: string
+  commitUuid: string
+  documentLogId: number
+}
+
 export type WebServerToClientEvents = {
   evaluationStatus: (args: EvaluationStatusArgs) => void
   evaluationResultCreated: (args: evaluationResultCreatedArgs) => void
   joinWorkspace: (args: { workspaceId: number; userId: string }) => void
+  documentLogCreated: (args: DocumentLogCreatedArgs) => void
 }
+
 export type WebClientToServerEvents = {
   joinWorkspace: (args: { workspaceId: number; userId: string }) => void
 }
@@ -64,4 +73,8 @@ export type WorkersClientToServerEvents = {
     workspaceId: number
     data: evaluationResultCreatedArgs
   }) => void
+  documentLogCreated: (args: {
+    workspaceId: number
+    data: DocumentLogCreatedArgs
+  }) => void
 }
diff --git a/packages/web-ui/src/ds/atoms/CircularProgress/index.tsx b/packages/web-ui/src/ds/atoms/CircularProgress/index.tsx
new file mode 100644
index 000000000..4e7995042
--- /dev/null
+++ b/packages/web-ui/src/ds/atoms/CircularProgress/index.tsx
@@ -0,0 +1,80 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+
+import { cn } from '../../../lib/utils'
+import { colors, TextColor } from '../../tokens'
+
+export type CircularProgressProps = {
+  value: number
+  color?: TextColor
+  backgroundColor?: TextColor
+  size?: number
+  strokeWidth?: number
+  className?: string
+  animateOnMount?: boolean
+}
+
+export function CircularProgress({
+  value: valueProp,
+  color = 'primary',
+  backgroundColor,
+  size = 14,
+  strokeWidth = 3,
+  className,
+  animateOnMount = true,
+}: CircularProgressProps) {
+  const [value, setValue] = useState(animateOnMount ? 0 : valueProp)
+
+  useEffect(() => {
+    if (animateOnMount) setValue(valueProp)
+  }, [])
+
+  useEffect(() => {
+    setValue(valueProp)
+  }, [valueProp])
+
+  const radius = (size - strokeWidth) / 2
+  const circumference = 2 * Math.PI * radius
+  const progress = value * circumference
+
+  return (
+    <svg
+      width={size}
+      height={size}
+      className={cn('-rotate-90', colors.textColors[color], className)}
+    >
+      {backgroundColor && (
+        <circle
+          className={cn(
+            'transition-all duration-300 ease-in-out',
+            colors.textColors[backgroundColor],
+          )}
+          stroke='currentColor'
+          fill='transparent'
+          strokeWidth={strokeWidth}
+          strokeDasharray={circumference}
+          strokeDashoffset={progress - circumference}
+          strokeLinecap='round'
+          r={radius}
+          cx={size / 2}
+          cy={size / 2}
+        />
+      )}
+      <circle
+        className='transition-all duration-300 ease-in-out'
+        stroke='currentColor'
+        fill='transparent'
+        strokeWidth={strokeWidth}
+        strokeDasharray={circumference}
+        strokeDashoffset={progress - circumference}
+        strokeLinecap='round'
+        r={radius}
+        cx={size / 2}
+        cy={size / 2}
+      />
+    </svg>
+  )
+}
+
+export default CircularProgress
diff --git a/packages/web-ui/src/ds/atoms/index.ts b/packages/web-ui/src/ds/atoms/index.ts
index 22546aee4..3a2178fac 100644
--- a/packages/web-ui/src/ds/atoms/index.ts
+++ b/packages/web-ui/src/ds/atoms/index.ts
@@ -29,4 +29,5 @@ export * from './Container'
 export * from './Dropzone'
 export * from './DropzoneInput'
 export * from './Charts'
+export * from './CircularProgress'
 export * from './CodeBlock'