Krow-workspace/issues-to-create.md

[Admin] Scaffold the Admin Console Web Application

Labels: infra, platform:admin, priority:high, sred-eligible Milestone: Phase 1: Foundation & Dev Environment Setup

🎯 Objective

Create the foundational scaffolding for a new, separate React application within the monorepo, which will serve as the Admin Console. This console will be the central hub for managing users, roles, and other system-level configurations.

🔬 SR&ED Justification

• Technological Uncertainty: What is the most efficient way to set up a second, independent React application within our existing Vite-based monorepo, ensuring that dependency management, build processes, and environment variable configurations are isolated from the main frontend-web app but still manageable from the root Makefile?
• Systematic Investigation: We will conduct experimental development to create a new admin-web/ directory. We will test different Vite configurations to ensure it can run concurrently with the main app. We will also experiment with npm workspaces or similar solutions to optimize shared, non-UI dependencies and update the root Makefile to orchestrate this new application.

Details

This is the first step in building our critical user management interface. The Admin Console will be a completely new application, not sharing any logic with the krowSDK facade. It will communicate directly with Firebase services.

✅ Acceptance Criteria

• A new directory admin-web/ is created at the project root.
• A new React + Vite application is correctly scaffolded inside admin-web/.
• The new admin application can be started independently using npm run dev from within its directory.
• Firebase SDK is installed and a basic firebase/config.js is created for the admin app, using its own set of environment variables (VITE_ADMIN_FIREBASE_*).
• A basic, protected "AdminLayout" component is created that checks if a logged-in user has the admin role before rendering content.
• The root Makefile is updated with new targets (make admin-install, make admin-dev) to manage this new application.

---

[Admin] Implement User Listing and Role Management

Labels: feature, platform:admin, priority:high, sred-eligible Milestone: Phase 1: Foundation & Dev Environment Setup

🎯 Objective

Develop the core user management interface in the Admin Console, allowing administrators to view a list of all system users and modify their roles.

🔬 SR&ED Justification

• Technological Uncertainty: What is the most performant and secure way to query and display a potentially large list of users from Firestore in a React application, implementing real-time updates and secure role modification? Key uncertainties involve structuring Firestore security rules to ensure only admins can read the full user list and write role changes, and designing a robust UI component that prevents accidental, irreversible role changes.
• Systematic Investigation: We will experiment with different Firestore queries (onSnapshot for real-time vs. getDocs for static lists) to evaluate performance. We will prototype and test Firestore security rules extensively. We will also build a reusable and secure "RoleSelector" component that includes confirmation dialogs to prevent unintended administrative actions.

Details

This feature is the primary function of the Admin Console MVP. It directly enables the unblocking of other teams by allowing admins to assign the correct roles (client, vendor, etc.) to newly registered users.

✅ Acceptance Criteria

• A new "Users" page is created in the Admin Console.
• The page fetches and displays a list of all users from the users collection in Firestore.
• The user list is displayed in a table showing at least full_name, email, and user_role.
• An administrator can change a user's user_role using a dropdown or select menu in the table.
• The role change is immediately reflected in Firestore upon selection.
• A confirmation modal is shown before the role change is finalized to prevent errors.
• Firestore security rules are implemented to ensure only authenticated users with user_role: 'admin' can read the users collection and write to the user_role field.

---

[Backend] Implement User Invitation Cloud Function

Labels: feature, platform:backend, priority:high, sred-eligible Milestone: Phase 1: Foundation & Dev Environment Setup

🎯 Objective

Create a secure, HTTP-triggered Cloud Function that handles the business logic for inviting new users to the platform.

🔬 SR&ED Justification

• Technological Uncertainty: What is the most secure and reliable method to generate a unique, single-use invitation token, associate it with an email and a specific role, and then securely verify this token upon user registration? The investigation will involve designing a data model for pending invitations in Firestore, implementing a secure token generation strategy (e.g., UUIDs), and creating a Cloud Function with robust input validation and IAM permissions to prevent unauthorized use.
• Systematic Investigation: We will experiment with different data structures in Firestore for storing pending invites (e.g., a top-level invites collection). We will develop and test an HTTP Cloud Function, ensuring it is protected by IAM and properly validates incoming requests (checking for admin privileges). We will also integrate an email sending service (e.g., SendGrid or Firebase's own Trigger Email extension) to dispatch the invitation emails.

Details

This backend function is the engine of our invitation system. It will be called by the Admin Console and will be responsible for creating a pending invitation and sending an email to the invitee.

✅ Acceptance Criteria

• A new HTTP-triggered Cloud Function, inviteUser, is created in the firebase/functions directory.
• The function is protected and can only be called by authenticated users with an admin custom claim.
• The function accepts a request body containing email and user_role.
• Upon being called, it creates a new document in a invites collection in Firestore.
• The new document contains the invitee's email, the assigned role, a uniquely generated token, and an expiration date.
• The function sends an email to the provided address containing a unique registration link (e.g., https://krow-workforce.com/register?invite_token=...).

---

[Admin] Implement User Invitation UI

Labels: feature, platform:admin, priority:high Milestone: Phase 1: Foundation & Dev Environment Setup

🎯 Objective

Build the user interface within the Admin Console that allows administrators to invite new users to the platform.

Details

This UI will serve as the frontend for the inviteUser Cloud Function. It provides a simple and intuitive way for admins to add new users without needing manual database intervention.

✅ Acceptance Criteria

• A new "Invite User" button or section is added to the "Users" page in the Admin Console.
• Clicking the button opens a modal or form with two fields: Email Address and User Role.
• The "User Role" field is a dropdown populated with the available roles (e.g., client, vendor, procurement).
• Submitting the form calls the inviteUser Cloud Function with the provided data.
• The UI provides clear feedback to the administrator on success or failure of the invitation.
• (Optional) A new section or page is created to display a list of pending invitations from the invites collection in Firestore.