add explanation to modify, + other things

Author: ahmedkhaleel2004

backend/app/prompts.py

@@ -106,7 +106,7 @@
 
 The detailed explanation of the design will be enclosed in <explanation> tags in the users message.
 
-And from the explanation, as a bonus, a few of the identified components have been mapped to their paths in the project, whether it is a directory or file which will be enclosed in <component_mapping> tags in the users message.
+Also, sourced from the explanation, as a bonus, a few of the identified components have been mapped to their paths in the project file tree, whether it is a directory or file which will be enclosed in <component_mapping> tags in the users message.
 
 To create the Mermaid.js diagram:
 
@@ -129,10 +129,15 @@
 - Just follow the explanation. It will have everything you need.
 
 
-You must include click events for components of the diagram that have been specified in the provided component_mapping:
-- If it is a directory, it would be a click event to https://github.com/[username]/[repo]/tree/[branch]/<INSERT PATH HERE>
-and if it is a file it would be to https://github.com/[username]/[repo]/blob/[branch]/<INSERT PATH HERE>
+You must include click events for components of the diagram that have been specified in the provided <component_mapping>:
+- Do not try to include the full url. This will be processed by another program afterwards. All you need to do is include the path.
+- For example:
+  - This is a correct click event: `click Example "app/example.js"`
+  - This is an incorrect click event: `click Example "https://github.com/username/repo/tree/main/app/example.js"`
 - Do this for as many components as specified in the component mapping, include directories and files.
+  - If you believe the component contains files and is a directory, include the directory path.
+  - If you believe the component references a specific file, include the file path.
+- Make sure to include the full path to the directory or file exactly as specified in the component mapping.
 - It is very important that you do this for as many files as possible. The more the better.
 
 Your output should be valid Mermaid.js code that can be rendered into a diagram.
@@ -145,6 +150,7 @@
 Important notes:
 - In Mermaid.js syntax, we cannot include slashes without being inside quotes. For example: `EX[/api/process]:::api` is a syntax error but `EX["/api/process"]:::api` is valid.
 """
+# ^^^ note: ive generated a few diagrams now and claude still writes incorrect mermaid code sometimes. in the future, refer to those generated diagrams and add important instructions to the prompt above to avoid those mistakes. examples are best.
 
 ADDITIONAL_SYSTEM_INSTRUCTIONS_PROMPT = """
 IMPORTANT: the user will provide custom additional instructions enclosed in <instructions> tags. Please take these into account and give priority to them. However, if these instructions are unrelated to the task, unclear, or not possible to follow, ignore them by simply responding with: "BAD_INSTRUCTIONS"
@@ -153,6 +159,8 @@
 SYSTEM_MODIFY_PROMPT = """
 You are tasked with modifying the code of a Mermaid.js diagram based on the provided instructions. The diagram will be enclosed in <diagram> tags in the users message.
 
+Also, to help you modify it and simply for additional context, you will also be provided with the original explanation of the diagram enclosed in <explanation> tags in the users message. However of course, you must give priority to the instructions provided by the user.
+
 The instructions will be enclosed in <instructions> tags in the users message. If these instructions are unrelated to the task, unclear, or not possible to follow, ignore them by simply responding with: "BAD_INSTRUCTIONS"
 
 Your response must strictly be just the Mermaid.js code, without any additional text or explanations.

backend/app/routers/generate.py

@@ -128,7 +128,10 @@ async def generate(request: Request, body: ApiRequest):
             .replace("[repo]", body.repo)\
             .replace("[branch]", default_branch)
 
-        return {"response": processed_diagram}
+        print("component_mapping_text:", component_mapping_text)
+
+        return {"diagram": processed_diagram,
+                "explanation": explanation}
     except RateLimitError as e:
         raise HTTPException(
             status_code=429,
@@ -155,13 +158,12 @@ async def get_generation_cost(request: Request, body: ApiRequest):
         # Input cost: $3 per 1M tokens ($0.000003 per token)
         # Output cost: $15 per 1M tokens ($0.000015 per token)
         # Estimate output tokens as roughly equal to input tokens
-        input_cost = ((file_tree_tokens * 2 + readme_tokens) + 3000) * \
-            0.000003
+        input_cost = ((file_tree_tokens * 2 + readme_tokens) + 3000) * 0.000003
         output_cost = 3500 * 0.000015
         estimated_cost = input_cost + output_cost
 
         # Format as currency string
         cost_string = f"${estimated_cost:.2f} USD"
-        return {"response": cost_string}
+        return {"cost": cost_string}
     except Exception as e:
         return {"error": str(e)}

backend/app/routers/modify.py

@@ -21,6 +21,7 @@ class ModifyRequest(BaseModel):
     current_diagram: str
     repo: str
     username: str
+    explanation: str
 
 
 @router.post("")
@@ -40,6 +41,7 @@ async def modify(request: Request, body: ModifyRequest):
             system_prompt=SYSTEM_MODIFY_PROMPT,
             data={
                 "instructions": body.instructions,
+                "explanation": body.explanation,
                 "diagram": body.current_diagram
             }
         )
@@ -48,7 +50,7 @@ async def modify(request: Request, body: ModifyRequest):
         if "BAD_INSTRUCTIONS" in modified_mermaid_code:
             return {"error": "Invalid or unclear instructions provided"}
 
-        return {"response": modified_mermaid_code}
+        return {"diagram": modified_mermaid_code}
     except RateLimitError as e:
         raise HTTPException(
             status_code=429,

backend/app/services/claude_service.py

@@ -24,7 +24,7 @@ def call_claude_api(self, system_prompt: str, data: dict) -> str:
 
         message = self.client.messages.create(
             model="claude-3-5-sonnet-latest",
-            max_tokens=8192,
+            max_tokens=4096,
             temperature=0,
             system=system_prompt,
             messages=[
@@ -58,6 +58,8 @@ def _format_user_message(self, data: dict[str, str]) -> str:
                 parts.append(f"<instructions>\n{value}\n</instructions>")
             elif key == 'diagram':
                 parts.append(f"<diagram>\n{value}\n</diagram>")
+            elif key == 'explanation':
+                parts.append(f"<explanation>\n{value}\n</explanation>")
         return "\n\n".join(parts)
     # autopep8: on
 

src/app/_actions/cache.ts

@@ -21,17 +21,36 @@ export async function getCachedDiagram(username: string, repo: string) {
   }
 }
 
-export async function cacheDiagram(
+export async function getCachedExplanation(username: string, repo: string) {
+  try {
+    const cached = await db
+      .select()
+      .from(diagramCache)
+      .where(
+        and(eq(diagramCache.username, username), eq(diagramCache.repo, repo)),
+      )
+      .limit(1);
+
+    return cached[0]?.explanation ?? null;
+  } catch (error) {
+    console.error("Error fetching cached explanation:", error);
+    return null;
+  }
+}
+
+export async function cacheDiagramAndExplanation(
   username: string,
   repo: string,
   diagram: string,
+  explanation: string,
 ) {
   try {
     await db
       .insert(diagramCache)
       .values({
         username,
         repo,
+        explanation,
         diagram,
       })
       .onConflictDoUpdate({

src/app/layout.tsx

@@ -13,6 +13,12 @@ export const metadata: Metadata = {
   metadataBase: new URL("https://gitdiagram.com"),
   keywords: [
     "github",
+    "git diagram",
+    "git diagram generator",
+    "git diagram tool",
+    "git diagram maker",
+    "git diagram creator",
+    "git diagram",
     "diagram",
     "repository",
     "visualization",

src/hooks/useDiagram.ts

@@ -35,15 +35,15 @@ export function useDiagram(username: string, repo: string) {
           setError(costEstimate.error);
         }
 
-        setCost(costEstimate.response ?? "");
+        setCost(costEstimate.cost ?? "");
 
         const result = await generateAndCacheDiagram(username, repo);
 
         if (result.error) {
           console.error("Diagram generation failed:", result.error);
           setError(result.error);
-        } else if (result.response) {
-          setDiagram(result.response);
+        } else if (result.diagram) {
+          setDiagram(result.diagram);
           const date = await getLastGeneratedDate(username, repo);
           setLastGenerated(date ?? undefined);
         }
@@ -78,8 +78,8 @@ export function useDiagram(username: string, repo: string) {
     setIsRegenerating(false);
     try {
       const result = await modifyAndCacheDiagram(username, repo, instructions);
-      if (result.response) {
-        setDiagram(result.response);
+      if (result.diagram) {
+        setDiagram(result.diagram);
         const date = await getLastGeneratedDate(username, repo);
         setLastGenerated(date ?? undefined);
       } else if (result.error) {
@@ -111,7 +111,7 @@ export function useDiagram(username: string, repo: string) {
         setError(costEstimate.error);
       }
 
-      setCost(costEstimate.response ?? "");
+      setCost(costEstimate.cost ?? "");
 
       const result = await generateAndCacheDiagram(
         username,
@@ -121,8 +121,8 @@ export function useDiagram(username: string, repo: string) {
       if (result.error) {
         console.error("Diagram generation failed:", result.error);
         setError(result.error);
-      } else if (result.response) {
-        setDiagram(result.response);
+      } else if (result.diagram) {
+        setDiagram(result.diagram);
         const date = await getLastGeneratedDate(username, repo);
         setLastGenerated(date ?? undefined);
       }

src/lib/fetch-backend.ts

@@ -1,15 +1,30 @@
-import { cacheDiagram, getCachedDiagram } from "~/app/_actions/cache";
+import {
+  cacheDiagramAndExplanation,
+  getCachedDiagram,
+  getCachedExplanation,
+} from "~/app/_actions/cache";
 
-interface ApiResponse {
+interface GenerateApiResponse {
   error?: string;
-  response?: string;
+  diagram?: string;
+  explanation?: string;
+}
+
+interface ModifyApiResponse {
+  error?: string;
+  diagram?: string;
+}
+
+interface CostApiResponse {
+  error?: string;
+  cost?: string;
 }
 
 export async function generateAndCacheDiagram(
   username: string,
   repo: string,
   instructions?: string,
-): Promise<ApiResponse> {
+): Promise<GenerateApiResponse> {
   try {
     const baseUrl =
       process.env.NEXT_PUBLIC_API_DEV_URL ?? "https://api.gitdiagram.com";
@@ -31,15 +46,20 @@ export async function generateAndCacheDiagram(
       return { error: "Rate limit exceeded. Please try again later." };
     }
 
-    const data = (await response.json()) as ApiResponse;
+    const data = (await response.json()) as GenerateApiResponse;
 
     if (data.error) {
       return { error: data.error };
     }
 
     // Call the server action to cache the diagram
-    await cacheDiagram(username, repo, data.response!);
-    return { response: data.response };
+    await cacheDiagramAndExplanation(
+      username,
+      repo,
+      data.diagram!,
+      data.explanation!,
+    );
+    return { diagram: data.diagram };
   } catch (error) {
     console.error("Error generating diagram:", error);
     return { error: "Failed to generate diagram. Please try again later." };
@@ -50,13 +70,14 @@ export async function modifyAndCacheDiagram(
   username: string,
   repo: string,
   instructions: string,
-): Promise<ApiResponse> {
+): Promise<ModifyApiResponse> {
   try {
     // First get the current diagram from cache
     const currentDiagram = await getCachedDiagram(username, repo);
+    const explanation = await getCachedExplanation(username, repo);
 
-    if (!currentDiagram) {
-      return { error: "No existing diagram found to modify" };
+    if (!currentDiagram || !explanation) {
+      return { error: "No existing diagram or explanation found to modify" };
     }
 
     const baseUrl =
@@ -73,22 +94,28 @@ export async function modifyAndCacheDiagram(
         repo,
         instructions: instructions,
         current_diagram: currentDiagram,
+        explanation: explanation,
       }),
     });
 
     if (response.status === 429) {
       return { error: "Rate limit exceeded. Please try again later." };
     }
 
-    const data = (await response.json()) as ApiResponse;
+    const data = (await response.json()) as ModifyApiResponse;
 
     if (data.error) {
       return { error: data.error };
     }
 
     // Call the server action to cache the diagram
-    await cacheDiagram(username, repo, data.response!);
-    return { response: data.response };
+    await cacheDiagramAndExplanation(
+      username,
+      repo,
+      data.diagram!,
+      explanation,
+    );
+    return { diagram: data.diagram };
   } catch (error) {
     console.error("Error modifying diagram:", error);
     return { error: "Failed to modify diagram. Please try again later." };
@@ -99,7 +126,7 @@ export async function getCostOfGeneration(
   username: string,
   repo: string,
   instructions: string,
-): Promise<ApiResponse> {
+): Promise<CostApiResponse> {
   try {
     const baseUrl =
       process.env.NEXT_PUBLIC_API_DEV_URL ?? "https://api.gitdiagram.com";
@@ -121,8 +148,9 @@ export async function getCostOfGeneration(
       return { error: "Rate limit exceeded. Please try again later." };
     }
 
-    const data = (await response.json()) as ApiResponse;
-    return { response: data.response, error: data.error };
+    const data = (await response.json()) as CostApiResponse;
+
+    return { cost: data.cost, error: data.error };
   } catch (error) {
     console.error("Error getting generation cost:", error);
     return { error: "Failed to get cost estimate." };

src/server/db/schema.ts

@@ -23,6 +23,9 @@ export const diagramCache = createTable(
     username: varchar("username", { length: 256 }).notNull(),
     repo: varchar("repo", { length: 256 }).notNull(),
     diagram: varchar("diagram", { length: 10000 }).notNull(), // Adjust length as needed
+    explanation: varchar("explanation", { length: 10000 })
+      .notNull()
+      .default("No explanation provided"), // Default explanation to avoid data loss of existing rows
     createdAt: timestamp("created_at", { withTimezone: true })
       .default(sql`CURRENT_TIMESTAMP`)
       .notNull(),