From e12ac7c0ff5989133f332cc49352f13479b80230 Mon Sep 17 00:00:00 2001
From: William Le Roux <william@le-roux.ovh>
Date: Sat, 18 Oct 2025 17:12:11 +0000
Subject: [PATCH] Refactor repository handling and service integration

- Replaced GitHubService with RepositoryService for commit history and readme fetching.
- Introduced RepositoryDescriptor type to standardize repository information.
- Updated ProjectList, CommitHistory, ContributionMetrics, and other components to utilize the new repository structure.
- Enhanced URL parsing and repository descriptor creation for better flexibility.
- Removed deprecated GitHubService and migrated all related functionality to RepositoryService.
- Added unit tests for repository utility functions to ensure correct parsing and URL generation.
---
 .../page/dashboard/CreateProjectModal.tsx     |   8 +-
 .../components/page/dashboard/ProjectCard.tsx |   8 +-
 .../components/page/dashboard/ProjectList.jsx |  11 +-
 .../components/page/project/CommitHistory.jsx |  35 +-
 .../page/project/ContributionMetrics.tsx      |  16 +-
 .../components/page/project/LatestCommit.tsx  |   2 +-
 .../components/page/project/ProjectInfo.astro |  42 +-
 .../components/page/project/ReadMoreModal.tsx |  24 +-
 .../components/page/project/ReadmeViewer.tsx  |   2 +-
 .../page/project/UpdateHashModal.tsx          |   2 +-
 dapp/src/pages/project/index.astro            |   8 +-
 .../src/service/ContributionMetricsService.ts |  13 +-
 dapp/src/service/GithubService.ts             | 163 -------
 dapp/src/service/RepositoryService.ts         | 461 ++++++++++++++++++
 dapp/src/service/StateService.ts              |  56 ++-
 dapp/src/types/projectConfig.ts               |   3 +
 dapp/src/types/repository.ts                  |  21 +
 dapp/src/utils/editLinkFunctions.ts           |  58 ++-
 dapp/src/utils/repository.ts                  | 343 +++++++++++++
 dapp/src/utils/utils.ts                       |  30 +-
 dapp/tests/unit/repository-utils.spec.ts      |  37 ++
 21 files changed, 1060 insertions(+), 283 deletions(-)
 delete mode 100644 dapp/src/service/GithubService.ts
 create mode 100644 dapp/src/service/RepositoryService.ts
 create mode 100644 dapp/src/types/repository.ts
 create mode 100644 dapp/src/utils/repository.ts
 create mode 100644 dapp/tests/unit/repository-utils.spec.ts

diff --git a/dapp/src/components/page/dashboard/CreateProjectModal.tsx b/dapp/src/components/page/dashboard/CreateProjectModal.tsx
index aed0f04a..eae1383d 100644
--- a/dapp/src/components/page/dashboard/CreateProjectModal.tsx
+++ b/dapp/src/components/page/dashboard/CreateProjectModal.tsx
@@ -345,8 +345,12 @@ ${maintainerGithubs.map((gh) => `[[PRINCIPALS]]\ngithub="${gh}"`).join("\n\n")}
       if (project && project.name && project.config && project.maintainers) {
         setProject(project);
 
-        const { username, repoName } = getAuthorRepo(project.config.url);
-        if (username && repoName) {
+        const { descriptor, username, repoName } = getAuthorRepo(
+          project.config.url,
+        );
+        if (descriptor) {
+          setProjectRepoInfo(descriptor);
+        } else if (username && repoName) {
           setProjectRepoInfo(username, repoName);
         }
 
diff --git a/dapp/src/components/page/dashboard/ProjectCard.tsx b/dapp/src/components/page/dashboard/ProjectCard.tsx
index 989e446c..7ab16c7b 100644
--- a/dapp/src/components/page/dashboard/ProjectCard.tsx
+++ b/dapp/src/components/page/dashboard/ProjectCard.tsx
@@ -38,8 +38,12 @@ const ProjectCard = ({ config }: { config: ProjectConfig }) => {
       const project = await getProjectFromName(config.projectName);
       if (project && project.name && project.config && project.maintainers) {
         setProject(project);
-        const { username, repoName } = getAuthorRepo(project.config.url);
-        if (username && repoName) {
+        const { descriptor, username, repoName } = getAuthorRepo(
+          project.config.url,
+        );
+        if (descriptor) {
+          setProjectRepoInfo(descriptor);
+        } else if (username && repoName) {
           setProjectRepoInfo(username, repoName);
         }
         const tomlData = await fetchTomlFromCid(project.config.ipfs);
diff --git a/dapp/src/components/page/dashboard/ProjectList.jsx b/dapp/src/components/page/dashboard/ProjectList.jsx
index 82cb1fe6..cad9d669 100644
--- a/dapp/src/components/page/dashboard/ProjectList.jsx
+++ b/dapp/src/components/page/dashboard/ProjectList.jsx
@@ -8,6 +8,7 @@ import {
 } from "../../../service/ReadContractService.ts";
 import { loadConfigData } from "../../../service/StateService.ts";
 import { convertGitHubLink } from "../../../utils/editLinkFunctions";
+import { parseRepositoryUrl } from "../../../utils/repository";
 import { projectCardModalOpen } from "../../../utils/store.ts";
 import { extractConfigData } from "../../../utils/utils";
 import CreateProjectModal from "./CreateProjectModal.tsx";
@@ -214,6 +215,7 @@ const ProjectList = () => {
           const configData = extractConfigData(tomlData, project);
           setConfigInfo(configData);
         } else {
+          const repositoryDescriptor = parseRepositoryUrl(project.config.url);
           const configData = {
             projectName: project.name,
             logoImageLink: undefined,
@@ -222,8 +224,15 @@ const ProjectList = () => {
             organizationName: "",
             officials: {
               githubLink: project.config.url,
+              ...(repositoryDescriptor
+                ? { repository: repositoryDescriptor }
+                : {}),
+            },
+            socialLinks: {
+              twitter: "",
+              telegram: "",
+              discord: "",
             },
-            socialLinks: {},
             authorGithubNames: [],
             maintainersAddresses: project.maintainers,
           };
diff --git a/dapp/src/components/page/project/CommitHistory.jsx b/dapp/src/components/page/project/CommitHistory.jsx
index 220c4799..10805f43 100644
--- a/dapp/src/components/page/project/CommitHistory.jsx
+++ b/dapp/src/components/page/project/CommitHistory.jsx
@@ -1,6 +1,6 @@
 import { useStore } from "@nanostores/react";
 import { useEffect, useState } from "react";
-import { getCommitHistory } from "../../../service/GithubService.ts";
+import { getCommitHistory } from "../../../service/RepositoryService.ts";
 import {
   loadConfigData,
   loadProjectRepoInfo,
@@ -18,24 +18,35 @@ const CommitHistory = () => {
 
   const fetchCommitHistory = async (page = 1) => {
     const projectRepoInfo = loadProjectRepoInfo();
-    if (projectRepoInfo?.author && projectRepoInfo?.repository) {
-      const history = await getCommitHistory(
+    if (!projectRepoInfo) {
+      return;
+    }
+
+    let history = null;
+    if (projectRepoInfo.descriptor) {
+      history = await getCommitHistory(
+        projectRepoInfo.descriptor,
+        undefined,
+        page,
+      );
+    } else if (projectRepoInfo.author && projectRepoInfo.repository) {
+      history = await getCommitHistory(
         projectRepoInfo.author,
         projectRepoInfo.repository,
         page,
       );
+    }
 
-      if (history) {
-        setCommitHistory(history);
-        setCurrentPage(page);
+    if (history) {
+      setCommitHistory(history);
+      setCurrentPage(page);
 
-        // Set the latest commit
-        if (history.length > 0 && history[0].commits.length > 0) {
-          latestCommit.set(history[0].commits[0].sha);
-        }
-      } else {
-        setCommitHistory([]);
+      // Set the latest commit
+      if (history.length > 0 && history[0].commits.length > 0) {
+        latestCommit.set(history[0].commits[0].sha);
       }
+    } else {
+      setCommitHistory([]);
     }
   };
 
diff --git a/dapp/src/components/page/project/ContributionMetrics.tsx b/dapp/src/components/page/project/ContributionMetrics.tsx
index d878d1ca..1db117c3 100644
--- a/dapp/src/components/page/project/ContributionMetrics.tsx
+++ b/dapp/src/components/page/project/ContributionMetrics.tsx
@@ -8,14 +8,12 @@ import MonthlyActivityChart from "./MonthlyActivityChart";
 
 interface ContributionMetricsProps {
   projectName: string;
-  owner: string;
-  repo: string;
+  repositoryUrl: string;
 }
 
 const ContributionMetrics = ({
   projectName,
-  owner,
-  repo,
+  repositoryUrl,
 }: ContributionMetricsProps) => {
   const [metrics, setMetrics] = useState<ContributionMetricsType | null>(null);
   const [loading, setLoading] = useState(true);
@@ -28,10 +26,8 @@ const ContributionMetrics = ({
         setLoading(true);
         setError(null);
 
-        const metrics = await ContributionMetricsService.fetchMetrics(
-          owner,
-          repo,
-        );
+        const metrics =
+          await ContributionMetricsService.fetchMetrics(repositoryUrl);
         setMetrics(metrics);
 
         const configData = loadConfigData();
@@ -54,10 +50,10 @@ const ContributionMetrics = ({
       }
     };
 
-    if (projectName && owner && repo) {
+    if (projectName && repositoryUrl) {
       fetchMetrics();
     }
-  }, [projectName, owner, repo]);
+  }, [projectName, repositoryUrl]);
 
   if (loading) {
     return (
diff --git a/dapp/src/components/page/project/LatestCommit.tsx b/dapp/src/components/page/project/LatestCommit.tsx
index 9044b30b..55bdd80f 100644
--- a/dapp/src/components/page/project/LatestCommit.tsx
+++ b/dapp/src/components/page/project/LatestCommit.tsx
@@ -1,5 +1,5 @@
 import { useStore } from "@nanostores/react";
-import { getLatestCommitData } from "@service/GithubService";
+import { getLatestCommitData } from "@service/RepositoryService";
 import { getProjectHash } from "@service/ReadContractService";
 import { loadProjectInfo } from "@service/StateService";
 import Tooltip from "components/utils/Tooltip";
diff --git a/dapp/src/components/page/project/ProjectInfo.astro b/dapp/src/components/page/project/ProjectInfo.astro
index 9073d4e8..ed2c91fe 100644
--- a/dapp/src/components/page/project/ProjectInfo.astro
+++ b/dapp/src/components/page/project/ProjectInfo.astro
@@ -108,7 +108,7 @@ import Button from "components/utils/Button";
 <div id="read-more-modal-container"></div>
 
 <script>
-  import { getLatestCommitData } from "@service/GithubService";
+  import { getLatestCommitData } from "@service/RepositoryService";
   import { getIpfsBasicLink } from "utils/ipfsFunctions";
   import { navigate } from "astro:transitions/client";
   import type { ConfigData } from "types/projectConfig";
@@ -375,6 +375,11 @@ import Button from "components/utils/Button";
           projectNameElement.textContent = projectInfo.name;
         }
         const configData = loadConfigData();
+        const repoDetails = projectInfo?.config?.url
+          ? getAuthorRepo(projectInfo.config.url)
+          : undefined;
+        const repoHost = repoDetails?.descriptor?.host || "repository";
+        const repoDisplayName = repoHost.replace(/^www\./, "");
 
         const projectThumbnail = document.getElementById(
           "project-thumbnail",
@@ -428,6 +433,7 @@ import Button from "components/utils/Button";
               );
             }
           } else {
+            // Fallback to repo URL if no explicit officials provided
             addLinkButton(officialLinks, projectInfo.config.url, "github");
           }
         }
@@ -482,7 +488,9 @@ import Button from "components/utils/Button";
           link.appendChild(icon);
           link.appendChild(text);
 
-          syncStatusContainer.appendChild(link);
+          if (syncStatusContainer) {
+            syncStatusContainer.appendChild(link);
+          }
 
           // Add commit badge
           const latestSha = loadProjectLatestSha();
@@ -519,13 +527,11 @@ import Button from "components/utils/Button";
               ) {
                 commitIcon.src = "/icons/check.svg";
                 commitIcon.alt = "Check";
-                commitPopup.innerHTML =
-                  '<p class="text-sm w-36 sm:w-max">Commit SHA on-chain exists on GitHub</p>';
+                commitPopup.innerHTML = `<p class="text-sm w-36 sm:w-max">Commit SHA on-chain exists on ${repoDisplayName}</p>`;
               } else {
                 commitIcon.src = "/icons/check.svg";
                 commitIcon.alt = "Failed";
-                commitPopup.innerHTML =
-                  '<p class="text-sm w-36 sm:w-max">Commit SHA on-chain cannot be found on GitHub</p>';
+                commitPopup.innerHTML = `<p class="text-sm w-36 sm:w-max">Commit SHA on-chain cannot be found on ${repoDisplayName}</p>`;
               }
             } else {
               commitIcon.src = "/icons/failed.svg";
@@ -536,8 +542,7 @@ import Button from "components/utils/Button";
           } catch (error) {
             commitIcon.src = "/icons/failed.svg";
             commitIcon.alt = "Failed";
-            commitPopup.innerHTML =
-              '<p class="text-sm w-36 sm:w-max">No commit SHA can be found on-chain or on GitHub</p>';
+            commitPopup.innerHTML = `<p class="text-sm w-36 sm:w-max">No commit SHA can be found on-chain or on ${repoDisplayName}</p>`;
           }
         }
 
@@ -549,8 +554,10 @@ import Button from "components/utils/Button";
           logoImageLink: configData?.logoImageLink
             ? convertGitHubLink(configData.logoImageLink)
             : "",
-          githubUrl:
-            configData?.officials?.githubLink || projectInfo.config.url,
+          repositoryUrl:
+            configData?.officials?.repository?.url ||
+            configData?.officials?.githubLink ||
+            projectInfo.config.url,
           websiteUrl: configData?.officials?.websiteLink,
         };
 
@@ -579,13 +586,15 @@ import Button from "components/utils/Button";
         }
 
         if (projectInfo?.name && projectInfo?.config?.url) {
-          const { username, repoName } = getAuthorRepo(projectInfo.config.url);
-          if (username && repoName) {
+          const repositoryUrl =
+            configData?.officials?.repository?.url ||
+            repoDetails?.descriptor?.url ||
+            projectInfo.config.url;
+          if (repositoryUrl) {
             contributionMetricsRoot.render(
               React.createElement(ContributionMetrics, {
                 projectName: projectInfo.name,
-                owner: username,
-                repo: repoName,
+                repositoryUrl,
               }),
             );
           }
@@ -603,10 +612,11 @@ import Button from "components/utils/Button";
     });
 
     function addLinkButton(
-      container: HTMLElement,
+      container: HTMLElement | null,
       url: string,
       iconName: string,
     ) {
+      if (!container) return; // Defensive guard
       const button = document.createElement("a");
       button.href = url;
       button.target = "_blank";
@@ -678,7 +688,7 @@ import Button from "components/utils/Button";
               ul.appendChild(li);
             });
             secDiv.appendChild(ul);
-            contentDiv.appendChild(secDiv);
+            if (contentDiv) contentDiv.appendChild(secDiv);
           }
         });
       } catch (e) {
diff --git a/dapp/src/components/page/project/ReadMoreModal.tsx b/dapp/src/components/page/project/ReadMoreModal.tsx
index dccfae89..88d8350c 100644
--- a/dapp/src/components/page/project/ReadMoreModal.tsx
+++ b/dapp/src/components/page/project/ReadMoreModal.tsx
@@ -1,7 +1,7 @@
 import { useEffect, useState, useCallback } from "react";
 import type { FC } from "react";
 import Modal from "components/utils/Modal";
-import { fetchReadmeContentFromConfigUrl } from "../../../service/GithubService";
+import { fetchReadmeContentFromConfigUrl } from "../../../service/RepositoryService";
 import Markdown from "markdown-to-jsx";
 import "github-markdown-css";
 
@@ -15,7 +15,7 @@ interface ReadMoreModalProps {
     description: string;
     organization: string;
     logoImageLink: string;
-    githubUrl: string;
+    repositoryUrl: string;
     websiteUrl?: string;
   };
 }
@@ -62,10 +62,10 @@ const ReadMoreModal: FC<ReadMoreModalProps> = ({
 
   useEffect(() => {
     const loadReadme = async () => {
-      if (isOpen && projectData?.githubUrl) {
+      if (isOpen && projectData?.repositoryUrl) {
         try {
           const content = await fetchReadmeContentFromConfigUrl(
-            projectData.githubUrl,
+            projectData.repositoryUrl,
           );
           if (content) {
             setReadmeContent(content);
@@ -87,13 +87,13 @@ const ReadMoreModal: FC<ReadMoreModalProps> = ({
         setReadmeContent("");
       }
     };
-  }, [isOpen, projectData?.githubUrl]);
+  }, [isOpen, projectData?.repositoryUrl]);
 
   const handleGoToReleases = useCallback(() => {
-    if (projectData?.githubUrl) {
-      window.open(`${projectData.githubUrl}/releases`, "_blank");
+    if (projectData?.repositoryUrl) {
+      window.open(`${projectData.repositoryUrl}/releases`, "_blank");
     }
-  }, [projectData?.githubUrl]);
+  }, [projectData?.repositoryUrl]);
 
   if (!isOpen) return null;
 
@@ -115,9 +115,9 @@ const ReadMoreModal: FC<ReadMoreModalProps> = ({
                 {projectData?.name || ""}
               </p>
               <div className="flex items-center gap-3">
-                {projectData?.githubUrl && (
+                {projectData?.repositoryUrl && (
                   <a
-                    href={projectData.githubUrl}
+                    href={projectData.repositoryUrl}
                     target="_blank"
                     rel="noopener noreferrer"
                   >
@@ -154,8 +154,8 @@ const ReadMoreModal: FC<ReadMoreModalProps> = ({
                 <div className="flex items-center gap-2 w-full sm:w-auto">
                   <CopyButton
                     textToCopy={
-                      projectData?.githubUrl
-                        ? `git clone ${projectData.githubUrl}`
+                      projectData?.repositoryUrl
+                        ? `git clone ${projectData.repositoryUrl}`
                         : ""
                     }
                     showText={true}
diff --git a/dapp/src/components/page/project/ReadmeViewer.tsx b/dapp/src/components/page/project/ReadmeViewer.tsx
index f76210c7..c598b39a 100644
--- a/dapp/src/components/page/project/ReadmeViewer.tsx
+++ b/dapp/src/components/page/project/ReadmeViewer.tsx
@@ -1,7 +1,7 @@
 import { useStore } from "@nanostores/react";
 import Markdown from "markdown-to-jsx";
 import { useEffect, useState } from "react";
-import { fetchReadmeContentFromConfigUrl } from "../../../service/GithubService";
+import { fetchReadmeContentFromConfigUrl } from "../../../service/RepositoryService";
 import { loadProjectInfo } from "../../../service/StateService";
 import { projectInfoLoaded } from "../../../utils/store";
 import DOMPurify from "dompurify";
diff --git a/dapp/src/components/page/project/UpdateHashModal.tsx b/dapp/src/components/page/project/UpdateHashModal.tsx
index 9c1d9633..4c6df01d 100644
--- a/dapp/src/components/page/project/UpdateHashModal.tsx
+++ b/dapp/src/components/page/project/UpdateHashModal.tsx
@@ -1,5 +1,5 @@
 import { useStore } from "@nanostores/react";
-import { getLatestCommitHash } from "@service/GithubService";
+import { getLatestCommitHash } from "@service/RepositoryService";
 import { getProject } from "@service/ReadContractService";
 import { loadProjectInfo, setProject } from "@service/StateService";
 import { loadedPublicKey } from "@service/walletService";
diff --git a/dapp/src/pages/project/index.astro b/dapp/src/pages/project/index.astro
index 7ba8aee3..3e7136c0 100644
--- a/dapp/src/pages/project/index.astro
+++ b/dapp/src/pages/project/index.astro
@@ -43,9 +43,11 @@ import ProjectInfoTitle from "../../components/page/project/ProjectInfoTitle.ast
         const project = await getProjectFromName(projectName);
         if (project && project.name && project.config && project.maintainers) {
           setProject(project);
-          const { username, repoName } = getAuthorRepo(project.config.url);
-          if (username && repoName) {
-            setProjectRepoInfo(username, repoName);
+          const { descriptor } = getAuthorRepo(project.config.url);
+          if (descriptor) {
+            setProjectRepoInfo(descriptor);
+          } else {
+            setProjectRepoInfo(project.config.url);
           }
           const tomlData = await fetchTomlFromCid(project.config.ipfs);
           if (tomlData) {
diff --git a/dapp/src/service/ContributionMetricsService.ts b/dapp/src/service/ContributionMetricsService.ts
index 779a1109..e91061e5 100644
--- a/dapp/src/service/ContributionMetricsService.ts
+++ b/dapp/src/service/ContributionMetricsService.ts
@@ -1,27 +1,28 @@
 import { GitLogService } from "./GitLogService";
-import { getCommitHistory } from "./GithubService";
+import { getCommitHistory } from "./RepositoryService";
 import type { ContributionMetrics } from "../types/contributionMetrics";
 import type { FormattedCommit } from "../types/github";
+import type { RepositoryDescriptor } from "../types/repository";
 
 /**
- * Service for calculating contribution metrics from GitHub API commit data
+ * Service for calculating contribution metrics from repository commit data
  * Reuses the same data that CommitHistory component fetches (client-side only)
  */
 export class ContributionMetricsService {
   /**
-   * Fetch contribution metrics by analyzing GitHub API commit data
+   * Fetch contribution metrics by analyzing repository commit history
    * Uses the same getCommitHistory() function as CommitHistory component
    */
   static async fetchMetrics(
-    owner: string,
-    repo: string,
+    repository: RepositoryDescriptor | string,
+    repoName?: string,
   ): Promise<ContributionMetrics> {
     try {
       const allCommits: FormattedCommit[] = [];
       const maxPages = 34;
 
       for (let page = 1; page <= maxPages; page++) {
-        const history = await getCommitHistory(owner, repo, page, 30);
+        const history = await getCommitHistory(repository, repoName, page, 30);
         if (!history || history.length === 0) break;
 
         for (const dayGroup of history) {
diff --git a/dapp/src/service/GithubService.ts b/dapp/src/service/GithubService.ts
deleted file mode 100644
index 66b42963..00000000
--- a/dapp/src/service/GithubService.ts
+++ /dev/null
@@ -1,163 +0,0 @@
-import axios from "axios";
-
-import type { FormattedCommit } from "../types/github";
-import {
-  getAuthorRepo,
-  getGithubContentUrlFromReadmeUrl,
-} from "../utils/editLinkFunctions";
-
-async function getCommitHistory(
-  username: string,
-  repo: string,
-  page: number = 1,
-  perPage: number = 30,
-): Promise<{ date: string; commits: FormattedCommit[] }[] | null> {
-  try {
-    const response = await axios.get(
-      `https://api.github.com/repos/${username}/${repo}/commits`,
-      {
-        params: { per_page: perPage, page: page },
-        headers: { Accept: "application/vnd.github.v3+json" },
-      },
-    );
-
-    const formattedCommits = response.data.map((commit: any) => ({
-      message: commit.commit.message,
-      author: {
-        name: commit.commit.author.name,
-        html_url: commit.author ? commit.author.html_url : "",
-      },
-      commit_date: commit.commit.author.date,
-      html_url: commit.html_url,
-      sha: commit.sha,
-    }));
-
-    // Group commits by date
-    const groupedCommits = formattedCommits.reduce(
-      (acc: Record<string, FormattedCommit[]>, commit: FormattedCommit) => {
-        const date = new Date(commit.commit_date).toISOString().split("T")[0];
-        if (!date) {
-          return acc;
-        }
-        if (!acc[date]) {
-          acc[date] = [];
-        }
-        acc[date].push(commit);
-        return acc;
-      },
-      {},
-    );
-
-    // Convert grouped commits to array format
-    return Object.entries(groupedCommits).map(([date, commits]) => ({
-      date,
-      commits: commits as FormattedCommit[],
-    }));
-  } catch {
-    // Don't show error toast as this may be an expected condition
-    // (e.g., repository is private or doesn't exist)
-    return null;
-  }
-}
-
-async function getCommitDataFromSha(
-  owner: string,
-  repo: string,
-  sha: string,
-): Promise<any> {
-  try {
-    const url = `https://api.github.com/repos/${owner}/${repo}/commits/${sha}`;
-    const response = await fetch(url);
-
-    if (!response.ok) {
-      // Expected condition (commit may not exist)
-      return undefined;
-    }
-
-    return await response.json();
-  } catch {
-    // Don't show error toast as this may be an expected condition
-    return undefined;
-  }
-}
-
-async function getLatestCommitData(
-  configUrl: string,
-  sha: string,
-): Promise<any> {
-  const { username, repoName } = getAuthorRepo(configUrl);
-  if (!username || !repoName) {
-    // Expected condition (URL may be malformed)
-    return undefined;
-  }
-
-  return await getCommitDataFromSha(username, repoName, sha);
-}
-
-async function getLatestCommitHash(
-  configUrl: string,
-): Promise<string | undefined> {
-  const { username, repoName } = getAuthorRepo(configUrl);
-  if (!username || !repoName) {
-    // Expected condition (URL may be malformed)
-    return undefined;
-  }
-
-  try {
-    const repoRes = await fetch(
-      `https://api.github.com/repos/${username}/${repoName}`,
-    );
-    if (!repoRes.ok) {
-      // Expected condition (repo may not exist or be private)
-      return undefined;
-    }
-
-    const repoData = await repoRes.json();
-    const defaultBranch = repoData.default_branch;
-
-    const commitRes = await fetch(
-      `https://api.github.com/repos/${username}/${repoName}/commits/${defaultBranch}`,
-    );
-    if (!commitRes.ok) {
-      // Expected condition (branch may not exist)
-      return undefined;
-    }
-
-    const latestCommit = await commitRes.json();
-    const latestSha = latestCommit.sha;
-    return latestSha;
-  } catch {
-    // Don't show error toast as these are often expected conditions
-    return undefined;
-  }
-}
-
-async function fetchReadmeContentFromConfigUrl(configUrl: string) {
-  try {
-    const url = getGithubContentUrlFromReadmeUrl(configUrl);
-
-    if (url) {
-      const response = await fetch(url);
-
-      if (!response.ok) {
-        // Expected condition (readme may not exist)
-        return undefined;
-      }
-
-      const tomlText = await response.text();
-      return tomlText;
-    }
-
-    return undefined;
-  } catch {
-    // Don't show error toast as this may be an expected condition
-    return undefined;
-  }
-}
-
-export {
-  getCommitHistory,
-  fetchReadmeContentFromConfigUrl,
-  getLatestCommitData,
-  getLatestCommitHash,
-};
diff --git a/dapp/src/service/RepositoryService.ts b/dapp/src/service/RepositoryService.ts
new file mode 100644
index 00000000..f630b09e
--- /dev/null
+++ b/dapp/src/service/RepositoryService.ts
@@ -0,0 +1,461 @@
+import axios from "axios";
+
+import type { FormattedCommit } from "../types/github";
+import type { RepositoryDescriptor } from "../types/repository";
+import {
+  createRepositoryDescriptor,
+  ensureRepositoryDescriptor,
+  getDefaultBranch,
+  getRepositoryReadmeUrlAsync,
+  getRepositoryReadmeUrl,
+  getRawFileUrlAsync,
+  fetchDefaultBranch,
+  parseRepositoryUrl,
+} from "../utils/repository";
+
+interface CommitHistoryGroup {
+  date: string;
+  commits: FormattedCommit[];
+}
+
+interface ProviderAdapter {
+  getCommitHistory?: (
+    descriptor: RepositoryDescriptor,
+    page?: number,
+    perPage?: number,
+  ) => Promise<CommitHistoryGroup[] | null>;
+  getCommitBySha?: (
+    descriptor: RepositoryDescriptor,
+    sha: string,
+  ) => Promise<any>;
+  getLatestCommitHash?: (
+    descriptor: RepositoryDescriptor,
+  ) => Promise<string | undefined>;
+  getReadmeContent?: (
+    descriptor: RepositoryDescriptor,
+  ) => Promise<string | undefined>;
+}
+
+function groupCommitsByDate(
+  formattedCommits: FormattedCommit[],
+): CommitHistoryGroup[] {
+  const groupedCommits = formattedCommits.reduce(
+    (acc: Record<string, FormattedCommit[]>, commit: FormattedCommit) => {
+      const date = new Date(commit.commit_date).toISOString().split("T")[0];
+      if (!date) {
+        return acc;
+      }
+      if (!acc[date]) {
+        acc[date] = [];
+      }
+      acc[date].push(commit);
+      return acc;
+    },
+    {},
+  );
+
+  return Object.entries(groupedCommits).map(([date, commits]) => ({
+    date,
+    commits: commits as FormattedCommit[],
+  }));
+}
+
+const githubAdapter: ProviderAdapter = {
+  async getCommitHistory(descriptor, page = 1, perPage = 30) {
+    try {
+      const response = await axios.get(
+        `https://api.github.com/repos/${descriptor.owner}/${descriptor.name}/commits`,
+        {
+          params: { per_page: perPage, page },
+          headers: { Accept: "application/vnd.github.v3+json" },
+        },
+      );
+      const formatted: FormattedCommit[] = response.data.map((commit: any) => ({
+        message: commit.commit.message,
+        author: {
+          name: commit.commit.author.name,
+          html_url: commit.author ? commit.author.html_url : "",
+        },
+        commit_date: commit.commit.author.date,
+        html_url: commit.html_url,
+        sha: commit.sha,
+      }));
+      return groupCommitsByDate(formatted);
+    } catch {
+      return null;
+    }
+  },
+
+  async getCommitBySha(descriptor, sha) {
+    try {
+      const url = `https://api.github.com/repos/${descriptor.owner}/${descriptor.name}/commits/${sha}`;
+      const response = await fetch(url);
+
+      if (!response.ok) {
+        return undefined;
+      }
+
+      return await response.json();
+    } catch {
+      return undefined;
+    }
+  },
+
+  async getLatestCommitHash(descriptor) {
+    try {
+      const repoRes = await fetch(
+        `https://api.github.com/repos/${descriptor.owner}/${descriptor.name}`,
+      );
+      if (!repoRes.ok) {
+        return undefined;
+      }
+
+      const repoData = await repoRes.json();
+      const defaultBranch =
+        repoData.default_branch ?? getDefaultBranch(descriptor);
+
+      const commitRes = await fetch(
+        `https://api.github.com/repos/${descriptor.owner}/${descriptor.name}/commits/${defaultBranch}`,
+      );
+      if (!commitRes.ok) {
+        return undefined;
+      }
+
+      const latestCommit = await commitRes.json();
+      return latestCommit.sha;
+    } catch {
+      return undefined;
+    }
+  },
+
+  async getReadmeContent(descriptor) {
+    try {
+      // Prefer async URL with default-branch discovery
+      const url = await getRepositoryReadmeUrlAsync(descriptor);
+      if (!url) {
+        return undefined;
+      }
+
+      const response = await fetch(url);
+      if (!response.ok) {
+        return undefined;
+      }
+
+      return await response.text();
+    } catch {
+      return undefined;
+    }
+  },
+};
+
+const fallbackAdapter: ProviderAdapter = {
+  async getReadmeContent(descriptor) {
+    const url = await getRepositoryReadmeUrlAsync(descriptor);
+    if (!url) {
+      return undefined;
+    }
+    try {
+      const response = await fetch(url);
+      if (!response.ok) {
+        return undefined;
+      }
+      return await response.text();
+    } catch {
+      return undefined;
+    }
+  },
+};
+
+const gitlabAdapter: ProviderAdapter = {
+  async getCommitHistory(descriptor, page = 1, perPage = 30) {
+    try {
+      const projectId = encodeURIComponent(
+        `${descriptor.owner}/${descriptor.name}`,
+      );
+      const res = await axios.get(
+        `https://${descriptor.host}/api/v4/projects/${projectId}/repository/commits`,
+        { params: { per_page: perPage, page } },
+      );
+      const commits = res.data as any[];
+      const formatted: FormattedCommit[] = commits.map((c) => ({
+        message: c.title || c.message || "",
+        author: {
+          name: c.author_name || c.committer_name || "unknown",
+          html_url: `https://${descriptor.host}/${descriptor.owner}/${descriptor.name}/-/commit/${c.id}`,
+        },
+        commit_date: c.committed_date || c.created_at,
+        html_url: `https://${descriptor.host}/${descriptor.owner}/${descriptor.name}/-/commit/${c.id}`,
+        sha: c.id,
+      }));
+      return groupCommitsByDate(formatted);
+    } catch {
+      return null;
+    }
+  },
+  async getCommitBySha(descriptor, sha) {
+    try {
+      const projectId = encodeURIComponent(
+        `${descriptor.owner}/${descriptor.name}`,
+      );
+      const url = `https://${descriptor.host}/api/v4/projects/${projectId}/repository/commits/${sha}`;
+      const res = await fetch(url);
+      if (!res.ok) return undefined;
+      return await res.json();
+    } catch {
+      return undefined;
+    }
+  },
+  async getLatestCommitHash(descriptor) {
+    try {
+      const branch = await fetchDefaultBranch(descriptor);
+      const projectId = encodeURIComponent(
+        `${descriptor.owner}/${descriptor.name}`,
+      );
+      const url = `https://${descriptor.host}/api/v4/projects/${projectId}/repository/commits/${encodeURIComponent(branch)}`;
+      const res = await fetch(url);
+      if (!res.ok) return undefined;
+      const data = await res.json();
+      return data.id as string | undefined;
+    } catch {
+      return undefined;
+    }
+  },
+  async getReadmeContent(descriptor) {
+    try {
+      const url = await getRepositoryReadmeUrlAsync(descriptor);
+      if (!url) return undefined;
+      const res = await fetch(url);
+      if (!res.ok) return undefined;
+      return await res.text();
+    } catch {
+      return undefined;
+    }
+  },
+};
+
+const forgejoAdapter: ProviderAdapter = {
+  async getCommitHistory(descriptor, page = 1, perPage = 30) {
+    try {
+      const res = await axios.get(
+        `https://${descriptor.host}/api/v1/repos/${descriptor.owner}/${descriptor.name}/commits`,
+        { params: { page, limit: perPage } },
+      );
+      const commits = res.data as any[];
+      const formatted: FormattedCommit[] = commits.map((c) => ({
+        message: c.commit?.message || c.message || "",
+        author: {
+          name: c.commit?.author?.name || c.author?.login || "unknown",
+          html_url: `https://${descriptor.host}/${descriptor.owner}/${descriptor.name}/commit/${c.sha}`,
+        },
+        commit_date:
+          c.commit?.author?.date ||
+          c.committer?.date ||
+          c.created ||
+          new Date().toISOString(),
+        html_url: `https://${descriptor.host}/${descriptor.owner}/${descriptor.name}/commit/${c.sha}`,
+        sha: c.sha,
+      }));
+      return groupCommitsByDate(formatted);
+    } catch {
+      return null;
+    }
+  },
+  async getCommitBySha(descriptor, sha) {
+    try {
+      const url = `https://${descriptor.host}/api/v1/repos/${descriptor.owner}/${descriptor.name}/git/commits/${sha}`;
+      const res = await fetch(url);
+      if (!res.ok) return undefined;
+      return await res.json();
+    } catch {
+      return undefined;
+    }
+  },
+  async getLatestCommitHash(descriptor) {
+    try {
+      const branch = await fetchDefaultBranch(descriptor);
+      const url = `https://${descriptor.host}/api/v1/repos/${descriptor.owner}/${descriptor.name}/commits/${encodeURIComponent(branch)}`;
+      const res = await fetch(url);
+      if (!res.ok) return undefined;
+      const data = await res.json();
+      // For forgejo/gitea, this returns an array when asking branch commits; take first
+      const item = Array.isArray(data) ? data[0] : data;
+      return item?.sha as string | undefined;
+    } catch {
+      return undefined;
+    }
+  },
+  async getReadmeContent(descriptor) {
+    try {
+      const url = await getRepositoryReadmeUrlAsync(descriptor);
+      if (!url) return undefined;
+      const res = await fetch(url);
+      if (!res.ok) return undefined;
+      return await res.text();
+    } catch {
+      return undefined;
+    }
+  },
+};
+
+const bitbucketAdapter: ProviderAdapter = {
+  async getCommitHistory(descriptor, page = 1, perPage = 30) {
+    try {
+      const url = `https://api.bitbucket.org/2.0/repositories/${descriptor.owner}/${descriptor.name}/commits`;
+      const res = await axios.get(url, { params: { page, pagelen: perPage } });
+      const values = res.data?.values || [];
+      const formatted: FormattedCommit[] = values.map((c: any) => ({
+        message: c.message || "",
+        author: {
+          name: c.author?.user?.display_name || c.author?.raw || "unknown",
+          html_url:
+            c.links?.html?.href ||
+            `https://bitbucket.org/${descriptor.owner}/${descriptor.name}/commits/${c.hash}`,
+        },
+        commit_date: c.date,
+        html_url:
+          c.links?.html?.href ||
+          `https://bitbucket.org/${descriptor.owner}/${descriptor.name}/commits/${c.hash}`,
+        sha: c.hash,
+      }));
+      return groupCommitsByDate(formatted);
+    } catch {
+      return null;
+    }
+  },
+  async getCommitBySha(descriptor, sha) {
+    try {
+      const url = `https://api.bitbucket.org/2.0/repositories/${descriptor.owner}/${descriptor.name}/commit/${sha}`;
+      const res = await fetch(url);
+      if (!res.ok) return undefined;
+      return await res.json();
+    } catch {
+      return undefined;
+    }
+  },
+  async getLatestCommitHash(descriptor) {
+    try {
+      const branch = await fetchDefaultBranch(descriptor);
+      const url = `https://api.bitbucket.org/2.0/repositories/${descriptor.owner}/${descriptor.name}/commits/${encodeURIComponent(branch)}`;
+      const res = await fetch(url);
+      if (!res.ok) return undefined;
+      const data = await res.json();
+      const first = data?.values?.[0];
+      return first?.hash as string | undefined;
+    } catch {
+      return undefined;
+    }
+  },
+  async getReadmeContent(descriptor) {
+    try {
+      const url = await getRepositoryReadmeUrlAsync(descriptor);
+      if (!url) return undefined;
+      const res = await fetch(url);
+      if (!res.ok) return undefined;
+      return await res.text();
+    } catch {
+      return undefined;
+    }
+  },
+};
+
+function resolveAdapter(descriptor: RepositoryDescriptor): ProviderAdapter {
+  switch (descriptor.provider) {
+    case "github":
+      return githubAdapter;
+    case "gitlab":
+      return gitlabAdapter;
+    case "forgejo":
+      return forgejoAdapter;
+    case "bitbucket":
+      return bitbucketAdapter;
+    default:
+      return fallbackAdapter;
+  }
+}
+
+function resolveDescriptor(
+  ownerOrDescriptor: string | RepositoryDescriptor,
+  repoName?: string,
+): RepositoryDescriptor | undefined {
+  if (typeof ownerOrDescriptor !== "string") {
+    return ownerOrDescriptor;
+  }
+
+  if (repoName) {
+    return createRepositoryDescriptor({
+      host: "github.com",
+      owner: ownerOrDescriptor,
+      name: repoName,
+    });
+  }
+
+  return parseRepositoryUrl(ownerOrDescriptor);
+}
+
+export async function getCommitHistory(
+  ownerOrDescriptor: string | RepositoryDescriptor,
+  repoName?: string,
+  page: number = 1,
+  perPage: number = 30,
+): Promise<CommitHistoryGroup[] | null> {
+  const descriptor = resolveDescriptor(ownerOrDescriptor, repoName);
+  if (!descriptor) {
+    return null;
+  }
+
+  const adapter = resolveAdapter(descriptor);
+  if (!adapter.getCommitHistory) {
+    return null;
+  }
+
+  return adapter.getCommitHistory(descriptor, page, perPage);
+}
+
+export async function getLatestCommitData(
+  repository: string | RepositoryDescriptor,
+  sha: string,
+): Promise<any> {
+  const descriptor = ensureRepositoryDescriptor(repository);
+  if (!descriptor) {
+    return undefined;
+  }
+
+  const adapter = resolveAdapter(descriptor);
+  if (!adapter.getCommitBySha) {
+    return undefined;
+  }
+
+  return adapter.getCommitBySha(descriptor, sha);
+}
+
+export async function getLatestCommitHash(
+  repository: string | RepositoryDescriptor,
+): Promise<string | undefined> {
+  const descriptor = ensureRepositoryDescriptor(repository);
+  if (!descriptor) {
+    return undefined;
+  }
+
+  const adapter = resolveAdapter(descriptor);
+  if (!adapter.getLatestCommitHash) {
+    return undefined;
+  }
+
+  return adapter.getLatestCommitHash(descriptor);
+}
+
+export async function fetchReadmeContentFromConfigUrl(
+  repository: string | RepositoryDescriptor,
+): Promise<string | undefined> {
+  const descriptor = ensureRepositoryDescriptor(repository);
+  if (!descriptor) {
+    return undefined;
+  }
+
+  const adapter = resolveAdapter(descriptor);
+  if (!adapter.getReadmeContent) {
+    return undefined;
+  }
+
+  return adapter.getReadmeContent(descriptor);
+}
diff --git a/dapp/src/service/StateService.ts b/dapp/src/service/StateService.ts
index e9ab1380..b21de3f7 100644
--- a/dapp/src/service/StateService.ts
+++ b/dapp/src/service/StateService.ts
@@ -3,7 +3,12 @@ import * as pkg from "js-sha3";
 const { keccak256 } = pkg;
 import { Buffer } from "buffer";
 import type { Project } from "../../packages/tansu";
+import type { RepositoryDescriptor } from "../types/repository";
 import type { ConfigData } from "../types/projectConfig";
+import {
+  createRepositoryDescriptor,
+  parseRepositoryUrl,
+} from "../utils/repository";
 import { projectState as projectStateStore } from "utils/store";
 import { projectInfo as projectInfoStore } from "utils/store";
 import { projectRepoInfo as projectRepoInfoStore } from "utils/store";
@@ -29,11 +34,9 @@ const projectInfo: {
 };
 
 const projectRepoInfo: {
-  project_author: string | undefined;
-  project_repository: string | undefined;
+  descriptor: RepositoryDescriptor | undefined;
 } = {
-  project_author: undefined,
-  project_repository: undefined,
+  descriptor: undefined,
 };
 
 const projectLatestSha: {
@@ -54,10 +57,10 @@ function refreshLocalStorage(): void {
     projectInfo.project_maintainers = undefined;
     projectInfo.project_config_url = undefined;
     projectInfo.project_config_ipfs = undefined;
-    projectRepoInfo.project_author = undefined;
-    projectRepoInfo.project_repository = undefined;
+    projectRepoInfo.descriptor = undefined;
     projectLatestSha.sha = undefined;
     configData = undefined;
+    projectRepoInfoStore.set(undefined);
   }
 }
 
@@ -87,11 +90,35 @@ function setProject(project: Project): void {
   }
 }
 
-function setProjectRepoInfo(author: string, repository: string): void {
-  projectRepoInfo.project_author = author;
-  projectRepoInfo.project_repository = repository;
+function setProjectRepoInfo(
+  repository: RepositoryDescriptor | string,
+  repoName?: string,
+): void {
+  let descriptor: RepositoryDescriptor | undefined;
+
+  if (typeof repository !== "string") {
+    descriptor = repository;
+  } else if (repoName) {
+    descriptor = createRepositoryDescriptor({
+      host: "github.com",
+      owner: repository,
+      name: repoName,
+    });
+  } else {
+    descriptor = parseRepositoryUrl(repository) ?? undefined;
+  }
+
+  projectRepoInfo.descriptor = descriptor;
   if (typeof window !== "undefined") {
-    projectRepoInfoStore.set(projectRepoInfo);
+    if (descriptor) {
+      projectRepoInfoStore.set({
+        descriptor,
+        author: descriptor.owner,
+        repository: descriptor.name,
+      });
+    } else {
+      projectRepoInfoStore.set(undefined);
+    }
   }
 }
 
@@ -144,14 +171,15 @@ function loadProjectInfo(): Project | undefined {
 }
 
 function loadProjectRepoInfo():
-  | { author: string; repository: string }
+  | { author: string; repository: string; descriptor: RepositoryDescriptor }
   | undefined {
-  if (!projectRepoInfo.project_author || !projectRepoInfo.project_repository) {
+  if (!projectRepoInfo.descriptor) {
     return undefined;
   }
   return {
-    author: projectRepoInfo.project_author,
-    repository: projectRepoInfo.project_repository,
+    author: projectRepoInfo.descriptor.owner,
+    repository: projectRepoInfo.descriptor.name,
+    descriptor: projectRepoInfo.descriptor,
   };
 }
 
diff --git a/dapp/src/types/projectConfig.ts b/dapp/src/types/projectConfig.ts
index 02f871a7..b830883f 100644
--- a/dapp/src/types/projectConfig.ts
+++ b/dapp/src/types/projectConfig.ts
@@ -1,3 +1,5 @@
+import type { RepositoryDescriptor } from "./repository";
+
 export interface ConfigData {
   projectName: string;
   logoImageLink: string;
@@ -7,6 +9,7 @@ export interface ConfigData {
   officials: {
     websiteLink: string;
     githubLink: string;
+    repository?: RepositoryDescriptor;
   };
   socialLinks: {
     twitter: string;
diff --git a/dapp/src/types/repository.ts b/dapp/src/types/repository.ts
new file mode 100644
index 00000000..f9c98a07
--- /dev/null
+++ b/dapp/src/types/repository.ts
@@ -0,0 +1,21 @@
+export type RepositoryProvider =
+  | "github"
+  | "gitlab"
+  | "forgejo"
+  | "bitbucket"
+  | "unknown";
+
+export interface RepositoryDescriptor {
+  /** Hostname where the repository is hosted (e.g. github.com) */
+  host: string;
+  /** Provider classification derived from the hostname */
+  provider: RepositoryProvider;
+  /** Repository owner/namespace */
+  owner: string;
+  /** Repository name */
+  name: string;
+  /** Optional ref (branch/tag) embedded in the original URL */
+  ref?: string;
+  /** Canonical HTTPS URL to the repository root */
+  url: string;
+}
diff --git a/dapp/src/utils/editLinkFunctions.ts b/dapp/src/utils/editLinkFunctions.ts
index cc4d1271..a53ecea9 100644
--- a/dapp/src/utils/editLinkFunctions.ts
+++ b/dapp/src/utils/editLinkFunctions.ts
@@ -1,3 +1,11 @@
+import type { RepositoryDescriptor } from "../types/repository";
+import {
+  ensureRepositoryDescriptor,
+  getRepositoryConfigUrl,
+  getRepositoryReadmeUrl,
+  parseRepositoryUrl,
+} from "./repository";
+
 export function convertGitHubLink(link: string): string {
   const githubFileRegex =
     /^https:\/\/github\.com\/([^/]+)\/([^/]+)\/blob\/(.+)$/;
@@ -12,42 +20,42 @@ export function convertGitHubLink(link: string): string {
   }
 }
 
-export function getGithubContentUrl(
-  username: string,
-  repoName: string,
-  filePath: string,
-): string {
-  return `https://raw.githubusercontent.com/${username}/${repoName}/${filePath}`;
-}
-
 export function getAuthorRepo(repoUrl: string): {
   username: string | undefined;
   repoName: string | undefined;
+  descriptor?: RepositoryDescriptor;
 } {
-  const match = repoUrl.match(/https\:\/\/github\.com\/([^\/]+)\/([^\/]+)/);
-  if (!match || !match[1] || !match[2])
+  const descriptor = parseRepositoryUrl(repoUrl);
+  if (!descriptor) {
     return { username: undefined, repoName: undefined };
-  return { username: match[1], repoName: match[2] };
+  }
+  return {
+    username: descriptor.owner,
+    repoName: descriptor.name,
+    descriptor,
+  };
 }
 
-export function getGithubContentUrlFromConfigUrl(
-  configUrl: string,
+export function getConfigContentUrlFromRepo(
+  repoUrl: string | RepositoryDescriptor,
 ): string | undefined {
-  const { username, repoName } = getAuthorRepo(configUrl);
-  if (username && repoName) {
-    // use master as GitHub will do an automatic redirection to main
-    return getGithubContentUrl(username, repoName, "master/tansu.toml");
+  const descriptor = ensureRepositoryDescriptor(repoUrl);
+  if (!descriptor) {
+    return undefined;
   }
-  return undefined;
+  return getRepositoryConfigUrl(descriptor);
 }
 
-export function getGithubContentUrlFromReadmeUrl(
-  configUrl: string,
+export function getReadmeContentUrlFromRepo(
+  repoUrl: string | RepositoryDescriptor,
 ): string | undefined {
-  const { username, repoName } = getAuthorRepo(configUrl);
-  if (username && repoName) {
-    // use master as GitHub will do an automatic redirection to main
-    return getGithubContentUrl(username, repoName, "master/README.md");
+  const descriptor = ensureRepositoryDescriptor(repoUrl);
+  if (!descriptor) {
+    return undefined;
   }
-  return undefined;
+  return getRepositoryReadmeUrl(descriptor);
 }
+
+// Backwards compatibility exports (existing imports expect these names)
+export const getGithubContentUrlFromConfigUrl = getConfigContentUrlFromRepo;
+export const getGithubContentUrlFromReadmeUrl = getReadmeContentUrlFromRepo;
diff --git a/dapp/src/utils/repository.ts b/dapp/src/utils/repository.ts
new file mode 100644
index 00000000..306d0375
--- /dev/null
+++ b/dapp/src/utils/repository.ts
@@ -0,0 +1,343 @@
+import type {
+  RepositoryDescriptor,
+  RepositoryProvider,
+} from "../types/repository";
+
+const DEFAULT_BRANCH: Record<RepositoryProvider, string> = {
+  github: "master",
+  gitlab: "master",
+  forgejo: "master",
+  bitbucket: "master",
+  unknown: "master",
+};
+
+function detectProvider(host: string): RepositoryProvider {
+  const normalized = host.toLowerCase();
+  if (normalized === "github.com" || normalized.endsWith(".github.com")) {
+    return "github";
+  }
+  if (normalized === "gitlab.com" || normalized.endsWith(".gitlab.com")) {
+    return "gitlab";
+  }
+  if (normalized === "bitbucket.org" || normalized.endsWith(".bitbucket.org")) {
+    return "bitbucket";
+  }
+  if (
+    normalized.includes("codeberg") ||
+    normalized.includes("forgejo") ||
+    normalized.includes("gitea")
+  ) {
+    return "forgejo";
+  }
+  return "unknown";
+}
+
+function createRepositoryDescriptor({
+  host,
+  owner,
+  name,
+  provider,
+  ref,
+  url,
+}: {
+  host: string;
+  owner: string;
+  name: string;
+  provider?: RepositoryProvider;
+  ref?: string;
+  url?: string;
+}): RepositoryDescriptor {
+  const normalizedHost = host.toLowerCase();
+  const derivedProvider = provider ?? detectProvider(normalizedHost);
+  const canonicalUrl = url ?? `https://${normalizedHost}/${owner}/${name}`;
+  const descriptor: RepositoryDescriptor = {
+    host: normalizedHost,
+    provider: derivedProvider,
+    owner,
+    name,
+    url: canonicalUrl,
+  };
+
+  if (ref) {
+    descriptor.ref = ref;
+  }
+
+  return descriptor;
+}
+
+export function parseRepositoryUrl(
+  repositoryUrl: string,
+): RepositoryDescriptor | undefined {
+  if (!repositoryUrl) {
+    return undefined;
+  }
+
+  try {
+    const parsed = new URL(repositoryUrl);
+    const segments = parsed.pathname
+      .replace(/\.git$/, "")
+      .split("/")
+      .filter(Boolean);
+
+    if (segments.length < 2) {
+      return undefined;
+    }
+
+    const [owner, name, maybeTree, maybeRef] = segments;
+    if (!owner || !name) {
+      return undefined;
+    }
+    // Support /tree/<ref> (GitHub) and /-/tree/<ref> (GitLab)
+    let ref: string | undefined;
+    if (maybeTree === "tree" && maybeRef) {
+      ref = maybeRef;
+    } else if (maybeTree === "-" && segments[3] === "tree" && segments[4]) {
+      ref = segments[4];
+    }
+    const descriptorInit = {
+      host: parsed.host,
+      owner,
+      name,
+      url: `${parsed.origin}/${owner}/${name}`,
+    };
+
+    return ref
+      ? createRepositoryDescriptor({ ...descriptorInit, ref })
+      : createRepositoryDescriptor(descriptorInit);
+  } catch {
+    return undefined;
+  }
+}
+
+export function ensureRepositoryDescriptor(
+  input: RepositoryDescriptor | string | undefined,
+  fallback?: {
+    owner: string;
+    name: string;
+    host?: string;
+    provider?: RepositoryProvider;
+    ref?: string;
+  },
+): RepositoryDescriptor | undefined {
+  if (!input && !fallback) {
+    return undefined;
+  }
+
+  if (typeof input === "string") {
+    const parsed = parseRepositoryUrl(input);
+    if (parsed) {
+      return parsed;
+    }
+    if (fallback) {
+      const options: {
+        host: string;
+        owner: string;
+        name: string;
+        provider?: RepositoryProvider;
+        ref?: string;
+      } = {
+        host: fallback.host ?? "github.com",
+        owner: fallback.owner,
+        name: fallback.name,
+      };
+
+      if (fallback.provider) {
+        options.provider = fallback.provider;
+      }
+      if (fallback.ref) {
+        options.ref = fallback.ref;
+      }
+
+      return createRepositoryDescriptor(options);
+    }
+    return undefined;
+  }
+
+  if (!input && fallback) {
+    const options: {
+      host: string;
+      owner: string;
+      name: string;
+      provider?: RepositoryProvider;
+      ref?: string;
+    } = {
+      host: fallback.host ?? "github.com",
+      owner: fallback.owner,
+      name: fallback.name,
+    };
+
+    if (fallback.provider) {
+      options.provider = fallback.provider;
+    }
+    if (fallback.ref) {
+      options.ref = fallback.ref;
+    }
+
+    return createRepositoryDescriptor(options);
+  }
+
+  return input as RepositoryDescriptor;
+}
+
+export function getDefaultBranch(descriptor: RepositoryDescriptor): string {
+  if (descriptor.ref) {
+    return descriptor.ref;
+  }
+  return DEFAULT_BRANCH[descriptor.provider] ?? DEFAULT_BRANCH.unknown;
+}
+
+export function getRawFileUrl(
+  descriptor: RepositoryDescriptor,
+  path: string,
+  options: { ref?: string } = {},
+): string | undefined {
+  const branch = options.ref ?? getDefaultBranch(descriptor);
+
+  switch (descriptor.provider) {
+    case "github":
+      return `https://raw.githubusercontent.com/${descriptor.owner}/${descriptor.name}/${branch}/${path}`;
+    case "gitlab":
+      return `https://${descriptor.host}/${descriptor.owner}/${descriptor.name}/-/raw/${branch}/${path}`;
+    case "forgejo":
+      return `https://${descriptor.host}/${descriptor.owner}/${descriptor.name}/raw/branch/${branch}/${path}`;
+    case "bitbucket":
+      return `https://api.bitbucket.org/2.0/repositories/${descriptor.owner}/${descriptor.name}/src/${branch}/${path}`;
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Fetch provider default branch using public APIs. Falls back to hardcoded default when unavailable.
+ */
+export async function fetchDefaultBranch(
+  descriptor: RepositoryDescriptor,
+): Promise<string> {
+  try {
+    // If ref is explicitly set, honor it
+    if (descriptor.ref) return descriptor.ref;
+
+    switch (descriptor.provider) {
+      case "github": {
+        const res = await fetch(
+          `https://api.github.com/repos/${descriptor.owner}/${descriptor.name}`,
+        );
+        if (!res.ok) break;
+        const data = await res.json();
+        if (data && typeof data.default_branch === "string") {
+          return data.default_branch as string;
+        }
+        break;
+      }
+      case "gitlab": {
+        const projectId = encodeURIComponent(
+          `${descriptor.owner}/${descriptor.name}`,
+        );
+        const res = await fetch(
+          `https://${descriptor.host}/api/v4/projects/${projectId}`,
+        );
+        if (!res.ok) break;
+        const data = await res.json();
+        if (data && typeof data.default_branch === "string") {
+          return data.default_branch as string;
+        }
+        break;
+      }
+      case "forgejo": {
+        // Forgejo/Gitea API v1
+        const res = await fetch(
+          `https://${descriptor.host}/api/v1/repos/${descriptor.owner}/${descriptor.name}`,
+        );
+        if (!res.ok) break;
+        const data = await res.json();
+        if (data && typeof data.default_branch === "string") {
+          return data.default_branch as string;
+        }
+        break;
+      }
+      case "bitbucket": {
+        const res = await fetch(
+          `https://api.bitbucket.org/2.0/repositories/${descriptor.owner}/${descriptor.name}`,
+        );
+        if (!res.ok) break;
+        const data = await res.json();
+        if (
+          data &&
+          data.mainbranch &&
+          typeof data.mainbranch.name === "string"
+        ) {
+          return data.mainbranch.name as string;
+        }
+        break;
+      }
+      default:
+        break;
+    }
+  } catch {
+    // fallthrough to hardcoded default
+  }
+  return DEFAULT_BRANCH[descriptor.provider] ?? DEFAULT_BRANCH.unknown;
+}
+
+/**
+ * Async variant that resolves branch using fetchDefaultBranch when no ref provided.
+ */
+export async function getRawFileUrlAsync(
+  descriptor: RepositoryDescriptor,
+  path: string,
+  options: { ref?: string } = {},
+): Promise<string | undefined> {
+  const branch = options.ref ?? (await fetchDefaultBranch(descriptor));
+  switch (descriptor.provider) {
+    case "github":
+      return `https://raw.githubusercontent.com/${descriptor.owner}/${descriptor.name}/${branch}/${path}`;
+    case "gitlab":
+      return `https://${descriptor.host}/${descriptor.owner}/${descriptor.name}/-/raw/${branch}/${path}`;
+    case "forgejo":
+      return `https://${descriptor.host}/${descriptor.owner}/${descriptor.name}/raw/branch/${branch}/${path}`;
+    case "bitbucket":
+      return `https://api.bitbucket.org/2.0/repositories/${descriptor.owner}/${descriptor.name}/src/${branch}/${path}`;
+    default:
+      return undefined;
+  }
+}
+
+export function getRepositoryReadmeUrl(
+  descriptorOrUrl: RepositoryDescriptor | string,
+): string | undefined {
+  const descriptor = ensureRepositoryDescriptor(descriptorOrUrl);
+  if (!descriptor) {
+    return undefined;
+  }
+  return getRawFileUrl(descriptor, "README.md");
+}
+
+export async function getRepositoryReadmeUrlAsync(
+  descriptorOrUrl: RepositoryDescriptor | string,
+  options: { ref?: string } = {},
+): Promise<string | undefined> {
+  const descriptor = ensureRepositoryDescriptor(descriptorOrUrl);
+  if (!descriptor) return undefined;
+  return getRawFileUrlAsync(descriptor, "README.md", options);
+}
+
+export function getRepositoryConfigUrl(
+  descriptorOrUrl: RepositoryDescriptor | string,
+): string | undefined {
+  const descriptor = ensureRepositoryDescriptor(descriptorOrUrl);
+  if (!descriptor) {
+    return undefined;
+  }
+  return getRawFileUrl(descriptor, "tansu.toml");
+}
+
+export async function getRepositoryConfigUrlAsync(
+  descriptorOrUrl: RepositoryDescriptor | string,
+  options: { ref?: string } = {},
+): Promise<string | undefined> {
+  const descriptor = ensureRepositoryDescriptor(descriptorOrUrl);
+  if (!descriptor) return undefined;
+  return getRawFileUrlAsync(descriptor, "tansu.toml", options);
+}
+
+export { createRepositoryDescriptor, detectProvider };
diff --git a/dapp/src/utils/utils.ts b/dapp/src/utils/utils.ts
index 98008994..da04ae0f 100644
--- a/dapp/src/utils/utils.ts
+++ b/dapp/src/utils/utils.ts
@@ -11,6 +11,8 @@ import {
   type ProposalView,
   type ProposalViewStatus,
 } from "types/proposal";
+import { parseRepositoryUrl } from "./repository";
+import type { ConfigData } from "../types/projectConfig";
 // Import the extracted IPFS functions have been moved to ipfsFunctions.ts
 
 export function truncateMiddle(str: string, maxLength: number): string {
@@ -26,27 +28,27 @@ export function truncateMiddle(str: string, maxLength: number): string {
   );
 }
 
-export function extractConfigData(tomlData: any, project: Project) {
+export function extractConfigData(tomlData: any, project: Project): ConfigData {
+  const repositoryDescriptor = parseRepositoryUrl(project.config.url || "");
+  const officials: ConfigData["officials"] = {
+    websiteLink: tomlData.DOCUMENTATION?.ORG_URL || "",
+    githubLink: project.config.url || "",
+  };
+  if (repositoryDescriptor) {
+    officials.repository = repositoryDescriptor;
+  }
+
   return {
     projectName: project.name,
     logoImageLink: tomlData.DOCUMENTATION?.ORG_LOGO || "",
     thumbnailImageLink: tomlData.DOCUMENTATION?.ORG_THUMBNAIL || "",
     description: tomlData.DOCUMENTATION?.ORG_DESCRIPTION || "",
     organizationName: tomlData.DOCUMENTATION?.ORG_NAME || "",
-    officials: {
-      websiteLink: tomlData.DOCUMENTATION?.ORG_URL || "",
-      githubLink: project.config.url || "",
-    },
+    officials,
     socialLinks: {
-      ...(tomlData.DOCUMENTATION?.ORG_TWITTER && {
-        twitter: tomlData.DOCUMENTATION.ORG_TWITTER,
-      }),
-      ...(tomlData.DOCUMENTATION?.ORG_TELEGRAM && {
-        telegram: tomlData.DOCUMENTATION.ORG_TELEGRAM,
-      }),
-      ...(tomlData.DOCUMENTATION?.ORG_DISCORD && {
-        discord: tomlData.DOCUMENTATION.ORG_DISCORD,
-      }),
+      twitter: tomlData.DOCUMENTATION?.ORG_TWITTER || "",
+      telegram: tomlData.DOCUMENTATION?.ORG_TELEGRAM || "",
+      discord: tomlData.DOCUMENTATION?.ORG_DISCORD || "",
     },
     authorGithubNames:
       tomlData.PRINCIPALS?.map((p: { github: string }) => p.github) || [],
diff --git a/dapp/tests/unit/repository-utils.spec.ts b/dapp/tests/unit/repository-utils.spec.ts
new file mode 100644
index 00000000..71c7eab0
--- /dev/null
+++ b/dapp/tests/unit/repository-utils.spec.ts
@@ -0,0 +1,37 @@
+import { test, expect } from "@playwright/test";
+import {
+  parseRepositoryUrl,
+  getRepositoryReadmeUrl,
+  getRepositoryConfigUrl,
+} from "../../src/utils/repository";
+
+// These are pure functions; we can validate parsing and URL building without network
+
+test.describe("repository utils", () => {
+  test("parseRepositoryUrl handles GitHub and refs", () => {
+    const basic = parseRepositoryUrl("https://github.com/org/repo");
+    expect(basic).toBeTruthy();
+    expect(basic!.host).toBe("github.com");
+    expect(basic!.owner).toBe("org");
+    expect(basic!.name).toBe("repo");
+    expect(basic!.url).toBe("https://github.com/org/repo");
+
+    const withRef = parseRepositoryUrl("https://github.com/org/repo/tree/dev");
+    expect(withRef).toBeTruthy();
+    expect(withRef!.ref).toBe("dev");
+  });
+
+  test("getRepositoryReadmeUrl builds raw URL for README.md", () => {
+    const url = getRepositoryReadmeUrl("https://github.com/org/repo");
+    expect(url).toBe(
+      "https://raw.githubusercontent.com/org/repo/master/README.md",
+    );
+  });
+
+  test("getRepositoryConfigUrl builds raw URL for tansu.toml", () => {
+    const url = getRepositoryConfigUrl("https://github.com/org/repo");
+    expect(url).toBe(
+      "https://raw.githubusercontent.com/org/repo/master/tansu.toml",
+    );
+  });
+});