Architectural Runway - atterdag/archflow-it-architecture-hub GitHub Wiki

🏗️ Architectural Runway: The Foundation of ArchFlow

The architectural runway defines the foundational technical capabilities, strategic choices, and core infrastructure that enable the efficient and continuous delivery of ArchFlow's features. It represents the technical investment required to support current and future development.

1. Core Infrastructure & Hosting

  • Backend & Database: Google Firebase (Firestore, Authentication)

    • Rationale: Firebase was chosen for its rapid development capabilities, real-time data synchronization, and managed backend services, significantly reducing operational overhead. It allows developers to focus on application logic rather than server management.
    • Firestore: This NoSQL, document-oriented database is ideal for ArchFlow due to its flexible schema, which can easily accommodate various architectural artifact types (Markdown content, Structurizr DSL, JSON-like structures for canvases). Its real-time listeners (onSnapshot) are crucial for instantly reflecting changes across the application. Data is structured hierarchically (artifacts/{appId}/users/{userId}/...) to ensure data isolation and security per user, leveraging Firebase's built-in security rules for granular access control.
    • Authentication: Firebase Authentication handles user identity management. Initially, anonymous authentication or custom tokens (__initial_auth_token) are used to provide immediate access and simple user segregation. This allows users to start documenting without a cumbersome sign-up process, while still ensuring their data is unique to their session or environment. Future enhancements could include social logins (Google, GitHub) for persistent, multi-device access.
    • Scalability: As a Google Cloud-backed service, Firebase provides inherent horizontal scalability for both database operations and authentication, capable of handling a growing number of users and artifacts without significant architectural changes.

  • Deployment: Static Site Hosting Platform (e.g., Netlify, Vercel, Firebase Hosting, GitHub Pages)

    • Rationale: Since ArchFlow's frontend is a React Single-Page Application (SPA) that interacts with Firebase APIs and external rendering services, it can be hosted as static files. This simplifies deployment, reduces hosting costs, and provides excellent performance globally via Content Delivery Networks (CDNs).
    • Choice: While any static host works, platforms like Netlify or Vercel offer continuous deployment from GitHub repositories, automating the build and deployment process on every code push, which aligns with agile development practices. Firebase Hosting is also a natural fit within the Google ecosystem.

2. Frontend Technology Stack

  • Frontend Framework: React.js

    • Rationale: React is a widely adopted, component-based JavaScript library for building user interfaces. Its declarative nature and efficient DOM updates make it suitable for dynamic applications like ArchFlow, where user interactions involve frequent state changes and rendering. The strong community support, extensive ecosystem, and emphasis on reusable components promote maintainability and development speed.
    • Key React Concepts: Utilizes functional components, useState for component-level state, useEffect for side effects (data fetching, API calls), and useContext for global state management (Firebase instances, user ID).

  • Styling Framework: Tailwind CSS

    • Rationale: Tailwind CSS is a utility-first CSS framework that enables rapid UI development directly in JSX. By composing pre-defined utility classes, it promotes consistency, reduces the need for custom CSS, and simplifies responsiveness across different screen sizes. Its "just-in-time" compilation ensures that only used styles are bundled, leading to highly optimized CSS file sizes.

  • State Management: React's Built-in Hooks (useState, useContext)

    • Rationale: For an application of ArchFlow's current complexity, React's native state management capabilities are sufficient. useState manages local component state, while useContext provides a performant way to share global instances like Firebase db, auth, and userId across the component tree without prop drilling. For more complex, large-scale state needs, external libraries like Zustand or Redux could be considered in the future, but are not on the immediate runway.

3. Key API & Tool Integrations

  • Generative AI: Gemini API (gemini-2.0-flash model)

    • Rationale: The Gemini API provides state-of-the-art generative AI capabilities from Google. The gemini-2.0-flash model is optimized for speed and cost-effectiveness, making it suitable for real-time content generation within the application.
    • Integration: API calls are made directly from the client-side React application using the standard fetch API. Prompts are constructed dynamically based on artifact type and user input, allowing the AI to generate relevant Markdown text for descriptions or Structurizr DSL for diagrams. The API key is handled securely by the Canvas environment at runtime, preventing client-side exposure.

  • Diagram Rendering: Kroki.io

    • Rationale: Kroki is an online service that renders various text-based diagram formats (including Structurizr DSL) into image formats like SVG. This offloads the complex rendering logic from the client-side application and provides a highly reliable and performant way to visualize "diagrams as code."
    • Integration: The application sends Structurizr DSL content as a POST request to Kroki's /structurizr/svg endpoint. The returned SVG string is then embedded directly into the React component using dangerouslySetInnerHTML, allowing for scalable and interactive diagram previews without complex client-side rendering engines.

  • Markdown Parsing/Rendering: Simple Custom Implementation (Placeholder)

    • Rationale: For initial development, a lightweight, custom Markdown-to-HTML conversion function is used. This allows for basic formatting (headings, bold, lists, code blocks) without introducing external dependencies immediately.
    • Future Consideration: For robust, spec-compliant Markdown rendering, including tables, footnotes, and advanced syntax, a dedicated library like react-markdown combined with remark-gfm would be adopted as the application matures.

4. Data Model & Relationships (Firestore Schema)

  • Firestore Security Rules: Critical for multi-user applications, Firestore security rules are implemented to ensure that users can only read and write their own data. The rules enforce request.auth.uid == resource.data.userId for private user data stored under artifacts/{appId}/users/{userId}/.... This is a non-negotiable security aspect.

  • systems Collection:

    • Purpose: Represents distinct IT systems or architectural domains.
    • Fields:
      • id (Firestore doc.id): Unique identifier for the system.
      • userId: Foreign key linking to the user who owns this system.
      • name: Human-readable name (e.g., "E-commerce Platform").
      • description: Overview of the system.
      • createdAt, updatedAt: Timestamps for auditing and sorting.

  • architectural_artifacts Collection:

    • Purpose: Stores all specific architectural documentation, diagrams, and decisions. This is the core content collection.
    • Fields:
      • id (Firestore doc.id): Unique identifier for the artifact.
      • userId: Foreign key to the owning user.
      • systemId: Foreign key to the parent system, establishing the primary relationship.
      • type: Categorizes the artifact (e.g., 'arc42-section', 'adr', 'c4-model', 'req42-req', 'inception-canvas', 'communication-canvas'). This field drives UI behavior and AI prompting.
      • title: Title of the specific artifact (e.g., "Building Block View", "ADR-001: Choose Database X").
      • content: The actual data of the artifact (Markdown string for text, Structurizr DSL string for C4 models).
      • relatedAdrs: An array of architectural_artifact.ids where type is 'adr'. Establishes many-to-many relationships.
      • relatedRequirements: An array of architectural_artifact.ids where type is 'req42-req'.
      • relatedC4Models: An array of architectural_artifact.ids where type is 'c4-model'.
      • createdAt, updatedAt: Timestamps.

5. Development & Build Tools

  • Node.js & npm/yarn: Standard JavaScript runtime and package managers for managing project dependencies (React, Firebase SDK, etc.) and running development scripts.
  • Webpack/Vite: (Implicitly used by create-react-app or similar setup). These bundlers compile and optimize the React application for deployment, including transpiling JSX/ES6, minifying code, and bundling assets.
  • Git & GitHub: Essential for version control, collaborative development, issue tracking (mapping directly to the User Stories), and continuous integration/delivery workflows.