feat: add SR&ED tracking and project management tools
This commit introduces several new files and updates to support SR&ED tracking and project management: - Adds a template for SR&ED tasks to standardize issue creation. - Adds a Makefile command to set up GitHub labels from a YAML file. - Adds a Makefile command to export SR&ED-eligible issues to a Markdown file. - Adds a Makefile command to create issues from a file. - Adds documentation for SR&ED tracking and development conventions. - Adds a YAML file to define GitHub labels. - Adds scripts to set up GitHub labels, export issues, and create issues from a file. - Updates the project plan to include SR&ED considerations. These changes aim to improve project organization, facilitate SR&ED claims, and streamline development workflows.
This commit is contained in:
bwnyasse
@@ -6,7 +6,7 @@ This document breaks down the technical roadmap into actionable tasks, assigned
|
||||
|
||||
## Milestone 1: Foundation & Dev Environment Setup
|
||||
|
||||
*Goal: Establish a fully functional, shared `dev` environment on GCP/Firebase that all developers can connect to.*
|
||||
*Goal: Establish a fully functional, shared `dev` environment on GCP/Firebase and validate that all core components (Web, Mobile, Backend) can be built, deployed, and connected.*
|
||||
|
||||
### Infrastructure & Tooling (Primarily CTO)
|
||||
- **Issue:** `[Infra] Setup Enpass for Team Credential Management`
|
||||
@@ -14,27 +14,45 @@ This document breaks down the technical roadmap into actionable tasks, assigned
|
||||
- **Issue:** `[Infra] Create GCP/Firebase Projects (dev, staging, prod)`
|
||||
- **Description:** Set up the three distinct Google Cloud projects and associated Firebase projects. Enable required APIs (Auth, Cloud SQL, Data Connect).
|
||||
- **Issue:** `[Infra] Create Multi-Env Makefile`
|
||||
- **Description:** Create the main `Makefile` inspired by the reference project. It should handle environment switching (`ENV=dev/staging`) and orchestrate all build/deploy tasks.
|
||||
- **Description:** Create the main `Makefile` to handle environment switching (`ENV=dev/staging`) and orchestrate all build/deploy tasks.
|
||||
- **Issue:** `[Infra] Setup Shared Dev Database`
|
||||
- **Description:** Provision the initial Cloud SQL for PostgreSQL instance for the `dev` environment.
|
||||
|
||||
### Backend & Web (Dev 1)
|
||||
- **Issue:** `[Backend] Define GraphQL Schema for Core Entities`
|
||||
- **Description:** Translate `Event`, `Staff`, `Vendor`, and `User` schemas from `api_specification.md` into `.gql` files for Data Connect.
|
||||
- **Issue:** `[Backend] Deploy Initial Schema & Operations to Dev Env`
|
||||
- **Description:** Use the `Makefile` to deploy the initial Data Connect schema and basic `list/get` queries to the `dev` project.
|
||||
- **Issue:** `[Web] Generate TypeScript SDK for Dev Env`
|
||||
- **Description:** Configure and run the SDK generation command to create the TypeScript SDK pointing to the `dev` environment.
|
||||
- **Issue:** `[Web] Connect Web App to Dev Backend`
|
||||
- **Description:** Modify the web app to use the generated SDK. The goal is to authenticate and display a list of events from the shared `dev` backend.
|
||||
- **Epic:** `[Onboarding] End-to-End Flow Validation with 'Event' Entity`
|
||||
- **Issue:** `[Backend] Define and Deploy 'Event' Schema`
|
||||
- **Description:** Translate the `Event` schema from the API specification into `.gql` files. Define the basic `listEvents` query and `createEvent` mutation. Use the `Makefile` to deploy this to the `dev` environment and validate that the `events` table is created in Cloud SQL.
|
||||
- **Issue:** `[Web] Generate TypeScript SDK for Dev Env`
|
||||
- **Description:** Configure and run the SDK generation command to create the TypeScript SDK pointing to the `dev` environment.
|
||||
- **Issue:** `[Web] Connect 'Events' Page to Dev Backend (PoC)`
|
||||
- **Description:** Modify the main web application's `Events.jsx` page. Replace the existing mock/Base44 data fetching with the new TanStack Query hooks from the generated SDK to display a list of events from our own `dev` backend. This validates the full end-to-end workflow on a real feature.
|
||||
|
||||
- **Epic:** `[Backend] KROW Schema Implementation`
|
||||
- **Issue:** `[Backend] Define GraphQL Schema for Remaining Core Entities`
|
||||
- **Description:** Translate `Staff`, `Vendor`, `User`, and other core schemas from the API specification into `.gql` files and deploy them.
|
||||
|
||||
### Mobile (Dev 2)
|
||||
- **Issue:** `[Mobile] Generate Flutter SDK for Dev Env`
|
||||
- **Description:** Configure and run the SDK generation command to create the Flutter SDK pointing to the `dev` environment.
|
||||
- **Issue:** `[Mobile] Implement Firebase Auth Flow`
|
||||
- **Description:** Ensure both mobile apps can sign in and sign up using Firebase Auth against the `dev` project.
|
||||
- **Issue:** `[Mobile] Create Proof-of-Concept Screen`
|
||||
- **Description:** Build a simple screen in the Staff app that authenticates and fetches a list of events from the `dev` backend using the new SDK.
|
||||
- **Epic:** `[Mobile] Analysis & Documentation`
|
||||
- **Issue:** `[Mobile-Doc] Analyze & Document Existing App Logic`
|
||||
- **Description:** Review the legacy Flutter codebases to identify and document key business logic and user flows.
|
||||
- **Issue:** `[Mobile-Doc] Create & Update Workflow Diagrams`
|
||||
- **Description:** Based on the analysis, create or update Mermaid diagrams for critical workflows and add them to the internal launchpad.
|
||||
|
||||
- **Epic:** `[Mobile] CI/CD & Skeleton App Setup`
|
||||
- **Issue:** `[Mobile-CI/CD] Configure CodeMagic & Firebase App Distribution`
|
||||
- **Description:** Set up CodeMagic and configure build workflows for iOS/Android with automated deployment to Firebase App Distribution.
|
||||
- **Issue:** `[Mobile-CI/CD] Initialize Skeleton Apps in Monorepo`
|
||||
- **Description:** Create new, clean Flutter projects for `client-app` and `staff-app` within the `mobile-apps` directory.
|
||||
- **Issue:** `[Mobile-CI/CD] Implement Initial CI/CD Pipeline`
|
||||
- **Description:** Create a "Hello World" version of the Staff app and validate that it can be automatically built and deployed to App Distribution.
|
||||
|
||||
- **Epic:** `[Mobile] Backend Integration Validation`
|
||||
- **Issue:** `[Mobile-Auth] Implement Firebase Auth Flow in Skeleton App`
|
||||
- **Description:** Add Firebase Authentication to the skeleton Staff app and ensure users can sign up/log in against the `dev` project.
|
||||
- **Issue:** `[Mobile-Backend] Generate Flutter SDK for Dev Env`
|
||||
- **Description:** Configure and run the SDK generation command to create the Flutter SDK for the `dev` environment.
|
||||
- **Issue:** `[Mobile-Backend] Create Proof-of-Concept Screen`
|
||||
- **Description:** Build a simple screen in the skeleton Staff app that, after login, fetches and displays a list of events from the `dev` backend using the new SDK.
|
||||
|
||||
---
|
||||
|
||||
@@ -44,15 +62,15 @@ This document breaks down the technical roadmap into actionable tasks, assigned
|
||||
|
||||
### Backend (Dev 1)
|
||||
- **Epic:** `[Backend] Implement Full API Logic`
|
||||
- **Description:** Create all necessary GraphQL queries and mutations in Data Connect for all entities defined in `api_specification.md`. Deploy them continuously to the `dev` environment.
|
||||
- **Description:** Create all necessary GraphQL queries and mutations in Data Connect for all entities. Deploy them continuously to the `dev` environment.
|
||||
|
||||
### Web (Dev 1, with support from Dev 2)
|
||||
- **Epic:** `[Web] Full Application Re-wiring`
|
||||
- **Description:** Systematically replace all data-fetching logic in the web app to use the TanStack Query hooks from the generated Data Connect SDK.
|
||||
|
||||
### Mobile (Dev 2)
|
||||
- **Epic:** `[Mobile] Full Application Re-wiring`
|
||||
- **Description:** Refactor the `repositories` and `api_providers` in both the Client and Staff Flutter apps to use the generated Data Connect SDK for all network calls.
|
||||
- **Epic:** `[Mobile] Port Features to New Apps`
|
||||
- **Description:** Systematically port the features and UI from the legacy apps into the new, clean skeleton apps, connecting them to the Data Connect backend via the generated SDK.
|
||||
|
||||
---
|
||||
|
||||
@@ -62,11 +80,11 @@ This document breaks down the technical roadmap into actionable tasks, assigned
|
||||
|
||||
### Infrastructure & DevOps (CTO & Team)
|
||||
- **Issue:** `[CI/CD] Configure Web App Deployment Pipeline`
|
||||
- **Description:** Set up a GitHub Actions pipeline that builds and deploys the web app to Firebase Hosting, with separate jobs for `staging` and `prod`.
|
||||
- **Issue:** `[CI/CD] Configure Mobile App Deployment with CodeMagic`
|
||||
- **Description:** Set up CodeMagic pipelines to build and deploy the iOS and Android apps to TestFlight/Play Store Internal Testing.
|
||||
- **Description:** Set up a GitHub Actions pipeline to build and deploy the web app to Firebase Hosting (`staging` and `prod`).
|
||||
- **Issue:** `[CI/CD] Finalize Production Mobile Deployment`
|
||||
- **Description:** Finalize the CodeMagic pipelines for deployment to TestFlight/Play Store production tracks.
|
||||
- **Issue:** `[CI/CD] Configure Backend Deployment Pipeline`
|
||||
- **Description:** Automate the deployment of the Data Connect schema and operations (`firebase deploy --only dataconnect`).
|
||||
- **Description:** Automate the deployment of the Data Connect schema and operations.
|
||||
- **Issue:** `[Data] Create & Test Initial Data Import Scripts`
|
||||
- **Description:** Write scripts to populate the production database with any necessary initial data.
|
||||
- **Issue:** `[QA] Deploy to Staging & Perform E2E Testing`
|
||||
@@ -74,4 +92,4 @@ This document breaks down the technical roadmap into actionable tasks, assigned
|
||||
- **Issue:** `[Ops] Final Production Deployment`
|
||||
- **Description:** Run the production deployment (`make deploy ENV=prod`) and execute data import scripts.
|
||||
- **Issue:** `[Ops] Setup Monitoring & Alerting`
|
||||
- **Description:** Configure monitoring dashboards in Google Cloud for the database, API, and application performance.
|
||||
- **Description:** Configure monitoring dashboards in Google Cloud for the database, API, and application performance.
|
||||
|
||||
77
docs/09-sred-tracking.md
Normal file
77
docs/09-sred-tracking.md
Normal file
@@ -0,0 +1,77 @@
|
||||
# SR&ED Project Documentation - KROW Platform
|
||||
|
||||
This document serves as the primary record for tracking Scientific Research and Experimental Development (SR&ED) activities for the KROW project. It translates our project plan into the language of technological uncertainty and systematic investigation, as required for SR&ED claims.
|
||||
|
||||
## Overall Technological Uncertainty
|
||||
|
||||
The core technological uncertainty of this project is whether a unified backend, built on the novel Firebase Data Connect service, can effectively and performantly serve a heterogeneous set of clients (a React web app and two Flutter mobile apps) while maintaining data integrity in a complex relational model (PostgreSQL). This involves overcoming challenges in schema management, SDK generation, and real-time data synchronization across platforms, for which no standard industry solution exists.
|
||||
|
||||
---
|
||||
|
||||
## Milestone 1: Foundation & Dev Environment Setup
|
||||
|
||||
### 1.1. Technological Uncertainty
|
||||
|
||||
Can we establish a stable, multi-environment (dev, staging, prod) development workflow for a complex monorepo that integrates a declarative backend (Data Connect), a web frontend, and mobile frontends? The primary challenge is to create a reproducible setup that overcomes the limitations of local emulation and allows for parallel, collaborative development on a shared cloud infrastructure without conflicts.
|
||||
|
||||
### 1.2. Hypothesis
|
||||
|
||||
By combining a multi-environment `Makefile`, Firebase project aliases, and auto-generated, environment-aware SDKs, we hypothesize that we can create a streamlined and scalable development workflow. This approach should allow developers to seamlessly switch between cloud environments and ensure that all client applications (web and mobile) are always interacting with the correct backend instance.
|
||||
|
||||
### 1.3. Experimental Work
|
||||
|
||||
*(This section can be auto-populated by running `make export-issues` with the appropriate filters/labels.)*
|
||||
|
||||
- **`[Infra] Create Multi-Env Makefile`:** Development of a script to manage different cloud environments, which is a non-trivial engineering task involving environment variable injection and conditional logic.
|
||||
- **`[Backend] Define GraphQL Schema & Deploy to Dev`:** Experimentation with the Data Connect schema-to-SQL generation process to validate its capabilities, performance with relational data, and limitations.
|
||||
- **`[Web/Mobile] Generate & Integrate SDKs`:** Systematic investigation into the interoperability of the auto-generated SDKs with modern frontend frameworks (React/TanStack Query and Flutter/BLoC).
|
||||
|
||||
### 1.4. Results & Learnings
|
||||
|
||||
*(To be filled out upon milestone completion.)*
|
||||
|
||||
---
|
||||
|
||||
## Milestone 2: Core Feature Implementation
|
||||
|
||||
### 2.1. Technological Uncertainty
|
||||
|
||||
Once the foundational architecture is in place, the next uncertainty is whether the declarative nature of Data Connect is powerful enough to handle the complex business logic required by the KROW platform. Can we implement features like multi-step event creation, real-time status updates, and complex data validation purely through GraphQL mutations and queries, without needing a separate, imperative logic layer (like traditional Cloud Functions)?
|
||||
|
||||
### 2.2. Hypothesis
|
||||
|
||||
We hypothesize that by leveraging advanced GraphQL features and the underlying power of PostgreSQL (accessible via Data Connect), we can encapsulate most, if not all, of the core business logic directly within our Data Connect backend. This would create a more maintainable and "self-documenting" system where the API definition itself contains the business rules.
|
||||
|
||||
### 2.3. Experimental Work
|
||||
|
||||
*(This section can be auto-populated by running `make export-issues` with the appropriate filters/labels.)*
|
||||
|
||||
- **`[Backend] Implement Full API Logic`:** This involves systematically testing the limits of Data Connect's mutation capabilities to handle transactional logic and data validation.
|
||||
- **`[Web/Mobile] Full Application Re-wiring`:** This work will test the performance and ergonomics of the generated SDKs at scale, across dozens of components and screens.
|
||||
|
||||
### 2.4. Results & Learnings
|
||||
|
||||
*(To be filled out upon milestone completion.)*
|
||||
|
||||
---
|
||||
|
||||
## Milestone 3: Production Readiness & Go-Live
|
||||
|
||||
### 3.1. Technological Uncertainty
|
||||
|
||||
The final uncertainty is whether our automated, monorepo-based deployment strategy is robust and reliable enough for production. Can we create CI/CD pipelines that can correctly build, test, and deploy three distinct artifacts (Web, Mobile, Backend) in a coordinated manner, while managing environment-specific configurations and secrets securely?
|
||||
|
||||
### 3.2. Hypothesis
|
||||
|
||||
We hypothesize that by using a combination of GitHub Actions for workflow orchestration and CodeMagic for specialized Flutter builds, managed by our central `Makefile`, we can create a fully automated "push-to-deploy" system for all environments.
|
||||
|
||||
### 3.3. Experimental Work
|
||||
|
||||
*(This section can be auto-populated by running `make export-issues` with the appropriate filters/labels.)*
|
||||
|
||||
- **`[CI/CD] Configure Deployment Pipelines`:** This involves significant engineering work to script and test the automated build and deployment processes for each part of the monorepo.
|
||||
- **`[Data] Create & Test Initial Data Import Scripts`:** Development of reliable and idempotent scripts to populate the production database.
|
||||
|
||||
### 3.4. Results & Learnings
|
||||
|
||||
*(To be filled out upon milestone completion.)*
|
||||
25
docs/10-development-conventions.md
Normal file
25
docs/10-development-conventions.md
Normal file
@@ -0,0 +1,25 @@
|
||||
# Development Conventions
|
||||
|
||||
This document outlines the development conventions for the KROW project, including our GitHub label system.
|
||||
|
||||
## GitHub Labels
|
||||
|
||||
We use a structured system of labels to categorize and prioritize our work. The single source of truth for all available labels, their descriptions, and their colors is the `labels.yml` file at the root of this repository.
|
||||
|
||||
To apply these labels to the GitHub repository, run the following command:
|
||||
```bash
|
||||
make setup-labels
|
||||
```
|
||||
|
||||
## GitHub Issue Template
|
||||
|
||||
To ensure consistency and capture all necessary information for both development and SR&ED tracking, we use a standardized issue template.
|
||||
|
||||
When creating a new issue on GitHub, select the **"SR&ED Task"** template. This will pre-populate the issue description with the following sections:
|
||||
|
||||
- **🎯 Objective:** A one-sentence summary of the goal.
|
||||
- **🔬 SR&ED Justification:** A section to detail the technological uncertainty and the systematic investigation.
|
||||
- **💻 Technical Implementation Notes:** A place for technical guidance for the developer.
|
||||
- **✅ Acceptance Criteria:** A checklist to define what "done" means for this task.
|
||||
|
||||
Using this template is mandatory for all new development tasks.
|
||||
Reference in New Issue
Block a user