From 26dff819a1083c7014a1fe938eb33b8a00f00980 Mon Sep 17 00:00:00 2001 From: Achintha Isuru Date: Sat, 15 Nov 2025 23:13:58 -0500 Subject: [PATCH] feat(diagrams): add comprehensive architecture and use case diagrams for client mobile application --- ...reate-full-architecture-diagram-flutter.md | 80 +++++++++++++++++++ .../assets/diagrams/diagrams-config.json | 26 +++++- .../client-mobile-application/api-map.mermaid | 55 +++++++++++++ .../backend-architecture.mermaid | 28 +++++++ ...hat.mermaid => use-case-flowchart.mermaid} | 0 .../use-case-flows.mermaid | 45 +++++++++++ 6 files changed, 233 insertions(+), 1 deletion(-) create mode 100644 docs/prompts/create-full-architecture-diagram-flutter.md create mode 100644 firebase/internal-launchpad/assets/diagrams/legacy/client-mobile-application/api-map.mermaid create mode 100644 firebase/internal-launchpad/assets/diagrams/legacy/client-mobile-application/backend-architecture.mermaid rename firebase/internal-launchpad/assets/diagrams/legacy/client-mobile-application/{use-case-flowchat.mermaid => use-case-flowchart.mermaid} (100%) create mode 100644 firebase/internal-launchpad/assets/diagrams/legacy/client-mobile-application/use-case-flows.mermaid diff --git a/docs/prompts/create-full-architecture-diagram-flutter.md b/docs/prompts/create-full-architecture-diagram-flutter.md new file mode 100644 index 00000000..3db25f0b --- /dev/null +++ b/docs/prompts/create-full-architecture-diagram-flutter.md @@ -0,0 +1,80 @@ +## What the prompt does +- Generate a full architecture diagram for a Flutter project based on the given overview and use case diagram +- The architecture diagram should include the frontend, backend, and database layers +- The architecture diagram should be generated using mermaid syntax + +## Assumption +- Flutter project is given +- Overview mermaid diagram is given +- Use case diagram is given +- Backend architecture mermaid diagram is given +- The backend architecture diagram should be generated based on the given overview and use case diagrams + +## How to use the prompt +For the given Flutter project, I want to generate a complete architecture document. Use the codebase together with the following Mermaid files: + +* `overview.mermaid` +* `api_map.mermaid` +* `backend_architecture.mermaid` +* `use_case_flows.mermaid` +* `use-case-flowchart.mermaid` (duplicate file if needed for additional reference) + +Your tasks: + +1. Analyze the **Flutter project structure**, the relevant backend integrations, and all provided Mermaid diagrams. + +2. Create a **comprehensive Markdown architecture document** (`architecture.md`) that includes: + + ### A. Introduction + + * High-level summary of the project. + * Brief description of the core purpose of the app. + + ### B. Full Architecture Overview + + * Explanation of app architecture used (e.g., layered architecture, MVVM, Clean Architecture, etc.). + * Description of key modules, layers, and responsibilities. + * Integration points between UI, domain, and data layers. + + ### C. Backend Architecture + + * Based on the backend diagrams, describe: + + * How GraphQL is used. + * How Firebase services (Auth, Firestore, Storage, Functions, etc.) are integrated. + * How the app communicates with the backend end-to-end. + * API flow between Flutter → GraphQL → Firebase. + + ### D. API Layer + + * Summaries of GraphQL queries, mutations, and subscriptions. + * Explanation of how the app handles API errors, retries, caching, and parsing. + * Any backend-dependent logic highlighted in diagrams. + + ### E. State Management + + * Identify the state management approach used (Bloc, Riverpod, Provider, Cubit, ValueNotifier, etc.). + * Explain: + + * Why this method was chosen. + * How state flows between UI, logic, and backend. + * How the state management integrates with the API layer. + + ### F. Use-Case Flows + + * Explain each major use case using the `use_case_flows.mermaid` and `use-case-flowchart.mermaid` diagrams. + * Describe the UI → Logic → Backend → Response cycle for each use case. + + ### G. Backend Replacement Section + + Add a dedicated section titled **“Replacing or Plugging in a New Backend: Considerations & Recommendations”**, including: + + * What parts of the codebase are tightly coupled to the current backend. + * What should be abstracted (e.g., repositories, services, DTOs, error handling). + * How to structure interfaces to allow backend swapping. + * Suggested design improvements to make the architecture more backend-agnostic. + * Migration strategies for replacing GraphQL + Firebase with another backend (REST, Supabase, Hasura, etc.). + +3. Make the Markdown document clear, well-structured, and easy for developers to use as a long-term reference. + +4. Output the final result as a **single `architecture.md` file**. diff --git a/firebase/internal-launchpad/assets/diagrams/diagrams-config.json b/firebase/internal-launchpad/assets/diagrams/diagrams-config.json index 8871db8a..4a8ea5c1 100644 --- a/firebase/internal-launchpad/assets/diagrams/diagrams-config.json +++ b/firebase/internal-launchpad/assets/diagrams/diagrams-config.json @@ -73,7 +73,7 @@ }, { "path": "assets/diagrams/legacy/staff-mobile-application/backend-architecture.mermaid", - "title": "Legacy App Use Cases", + "title": "Legacy App Backend Architecture", "type": "mermaid", "icon": "bi-diagram-2" }, @@ -82,5 +82,29 @@ "title": "Legacy App Overview", "type": "mermaid", "icon": "bi-phone" + }, + { + "path": "assets/diagrams/legacy/client-mobile-application/use-case-flowchart.mermaid", + "title": "Legacy App Use Cases", + "type": "mermaid", + "icon": "bi-diagram-2" + }, + { + "path": "assets/diagrams/legacy/client-mobile-application/api-map.mermaid", + "title": "Legacy App API Map", + "type": "mermaid", + "icon": "bi-phone" + }, + { + "path": "assets/diagrams/legacy/client-mobile-application/use-case-flows.mermaid", + "title": "Legacy App Use Cases BE Chart", + "type": "mermaid", + "icon": "bi-diagram-2" + }, + { + "path": "assets/diagrams/legacy/client-mobile-application/backend-architecture.mermaid", + "title": "Legacy App Backend Architecture", + "type": "mermaid", + "icon": "bi-diagram-2" } ] \ No newline at end of file diff --git a/firebase/internal-launchpad/assets/diagrams/legacy/client-mobile-application/api-map.mermaid b/firebase/internal-launchpad/assets/diagrams/legacy/client-mobile-application/api-map.mermaid new file mode 100644 index 00000000..6b07c81b --- /dev/null +++ b/firebase/internal-launchpad/assets/diagrams/legacy/client-mobile-application/api-map.mermaid @@ -0,0 +1,55 @@ +flowchart TD + subgraph "GraphQL API" + direction LR + subgraph "Queries" + Q1[getEvents] + Q2[getEventDetails] + Q3[getInvoices] + Q4[getInvoiceDetails] + Q5[getNotifications] + Q6[getNotificationDetails] + Q7[getProfile] + Q8[getAssignedStaff] + end + + subgraph "Mutations" + M1[createEvent] + M2[updateProfile] + M3[rateStaff] + M4[clockIn] + M5[clockOut] + M6[uploadProfilePicture] + end + end + + subgraph "Firebase" + direction LR + subgraph "Firestore Collections" + FS1[events] + FS2[invoices] + FS3[notifications] + FS4[users] + end + + subgraph "Firebase Storage" + FB1[Profile Pictures] + end + end + + Q1 --> FS1 + Q2 --> FS1 + Q3 --> FS2 + Q4 --> FS2 + Q5 --> FS3 + Q6 --> FS3 + Q7 --> FS4 + Q8 --> FS1 + Q8 --> FS4 + + M1 --> FS1 + M2 --> FS4 + M3 --> FS1 + M3 --> FS4 + M4 --> FS1 + M5 --> FS1 + M6 --> FB1 diff --git a/firebase/internal-launchpad/assets/diagrams/legacy/client-mobile-application/backend-architecture.mermaid b/firebase/internal-launchpad/assets/diagrams/legacy/client-mobile-application/backend-architecture.mermaid new file mode 100644 index 00000000..34de2da3 --- /dev/null +++ b/firebase/internal-launchpad/assets/diagrams/legacy/client-mobile-application/backend-architecture.mermaid @@ -0,0 +1,28 @@ +flowchart TD + subgraph "Client" + A[Flutter App] + end + + subgraph "Backend" + B[GraphQL Server - Node.js] + C[Firebase] + end + + subgraph "Firebase Services" + C1[Firebase Auth] + C2[Firebase Firestore] + C3[Firebase Storage] + end + + A -- "GraphQL Queries/Mutations" --> B + A -- "Authentication" --> C1 + + B -- "Data Operations" --> C2 + B -- "File Operations" --> C3 + + C1 -- "User Tokens" --> A + C2 -- "Data" --> B + C3 -- "Files" --> B + + B -- "Data/Files" --> A + \ No newline at end of file diff --git a/firebase/internal-launchpad/assets/diagrams/legacy/client-mobile-application/use-case-flowchat.mermaid b/firebase/internal-launchpad/assets/diagrams/legacy/client-mobile-application/use-case-flowchart.mermaid similarity index 100% rename from firebase/internal-launchpad/assets/diagrams/legacy/client-mobile-application/use-case-flowchat.mermaid rename to firebase/internal-launchpad/assets/diagrams/legacy/client-mobile-application/use-case-flowchart.mermaid diff --git a/firebase/internal-launchpad/assets/diagrams/legacy/client-mobile-application/use-case-flows.mermaid b/firebase/internal-launchpad/assets/diagrams/legacy/client-mobile-application/use-case-flows.mermaid new file mode 100644 index 00000000..85d5634a --- /dev/null +++ b/firebase/internal-launchpad/assets/diagrams/legacy/client-mobile-application/use-case-flows.mermaid @@ -0,0 +1,45 @@ +flowchart TD + subgraph "Sign-In Flow" + A1[User enters credentials] --> B1{SignInBloc}; + B1 --> C1[Firebase Auth: signInWithEmailAndPassword]; + C1 -- Success --> D1[Navigate to Home]; + C1 -- Failure --> E1[Show error message]; + end + + subgraph "Password Reset Flow" + A2[User requests password reset] --> B2{SignInBloc}; + B2 --> C2[Firebase Auth: sendPasswordResetEmail]; + C2 -- Email Sent --> D2[User clicks deep link]; + D2 --> E2[UI with new password fields]; + E2 --> F2{SignInBloc}; + F2 --> G2[Firebase Auth: confirmPasswordReset]; + G2 -- Success --> H2[Show success message]; + G2 -- Failure --> I2[Show error message]; + end + + subgraph "Event Listing Flow" + A3[User navigates to Events screen] --> B3{EventsBloc}; + B3 --> C3[GraphQL Query: getEvents]; + C3 --> D3[Firestore: events collection]; + D3 -- Returns event data --> C3; + C3 -- Returns data --> B3; + B3 --> E3[Display list of events]; + end + + subgraph "Create Event Flow" + A4[User submits new event form] --> B4{CreateEventBloc}; + B4 --> C4[GraphQL Mutation: createEvent]; + C4 --> D4[Firestore: events collection]; + D4 -- Success --> C4; + C4 -- Returns success --> B4; + B4 --> E4[Navigate to event details]; + end + + subgraph "Profile Viewing Flow" + A5[User navigates to Profile screen] --> B5{ProfileBloc}; + B5 --> C5[GraphQL Query: getProfile]; + C5 --> D5[Firestore: users collection]; + D5 -- Returns profile data --> C5; + C5 -- Returns data --> B5; + B5 --> E5[Display profile information]; + end