🚀 Blue River Enterprise

📘 Blue River Enterprise 4.0 – User Manual

This section explains how to use the Blue River Enterprise multi-tenant resource planning platform end-to-end. It is read-only and does not affect your data.

1. Quick Start Checklist

1. Sign up with your name, work email, and an Organization Name.
2. Log in using the same email and password.
3. Confirm your current organization in the top bar selector.
4. Add projects and consultants (via API, CSV import, or KV), then check:
   • Dashboard for overview and utilization,
   • Resource Planner for assignments view,
   • Team for organization members and invites.
5. Optionally upgrade to a paid plan via Stripe checkout for full subscription features.

2. Login, Signup & Sessions

2.1 Signup

• Use the Create Account form on the landing page.
• Required fields:
  • Full Name
  • Email – this becomes your login ID
  • Password – stored as salted SHA-256 hash
  • Organization Name – creates your first tenant
• On successful signup, an organization is created and you are set as Owner.
• If the email already exists, you will see a clear error message in the status panel.

2.2 Login

• Use the Login section with your email and password.
• On success:
  • A secure BR_SESSION cookie is set (HttpOnly, Secure).
  • Your default organization is loaded and the main app UI appears.
• On failure, the login panel shows an appropriate error (invalid email/password).

2.3 Logout

• Use the 🚪 Logout item in the sidebar.
• This clears the session cookie and returns you to the login page.

3. Organizations & Multi-Tenant Setup

3.1 Organization Selector (Top Bar)

• Top right dropdown shows all organizations you belong to.
• Each option displays: Name (Plan), for example:
  • Blue River Consulting (free)
  • Client XYZ (starter)

3.2 Switching Organizations

• Select another organization from the dropdown to switch context.
• The app sends a request to /api/organization/switch and updates:
  • Your current session orgId,
  • Your default organization for future logins.
• The page reloads to reflect the new organization (projects, team, etc).

3.3 Creating Additional Organizations

• In the organization selector, choose + Create New Organization.
• Provide a new organization name when prompted.
• A new tenant is created and you are set as Owner of that tenant.

4. Roles & Permissions

• Owner
  • Initial creator of the organization.
  • Cannot be removed from the organization by others.
  • Can invite and remove members, and manage subscriptions.
• Admin
  • Can invite and remove members (except the Owner).
  • Typically used for team leads or managers.
• Member
  • Standard user with access to dashboards, planner and data.
  • Cannot invite or remove other members.

5. Team Management & Invitations

5.1 Viewing Team Members

• Go to Team Members in the sidebar.
• You will see:
  • Name and email of each member.
  • Role (owner, admin, member).
  • Date joined.

5.2 Inviting New Users

• Owners/Admins see a + Invite Team Member button.
• Click to open the invite modal:
  • Enter the user’s email address.
  • Choose member or admin role.
• On success, the app shows a unique invite link:
  • Copy and send this link to the invitee (e.g. via email).
  • The link points to /invite/<inviteId> where the API exposes details.
• The invite is stored with status pending for 7 days.

5.3 Accepting Invitations (Flow)

1. The invited user signs up or logs in with the same email used in the invitation.
2. Your backend validates the invite via:
   • GET /api/invitation/:id – reads details.
   • POST /api/invitation/:id/accept – adds the user to the org.
3. On successful acceptance:
   • The membership is created with the defined role.
   • The invitation status is updated to accepted.

5.4 Removing Members

• Owners/Admins can remove non-owner members from Team Members.
• Click Remove on the relevant row.
• The member loses access to that organization but keeps their account for other organizations.

6. Practices (Business Units)

• Each organization has a default practice: OTHERS.
• Use practices to represent business units, service lines or departments (e.g. Cloud, Data, Security).
• Backend endpoints:
  • GET /api/practices – list practices for current org.
  • POST /api/practices – add a new practice using a short code.
  • DELETE /api/practices?code=... – remove a practice.

7. Projects

7.1 Data Model Overview

Each project is stored per organization with key pattern br_project:<orgId>:<projectId>.

Important fields include:

• id, name, practice
• consultant (primary contact), hours
• start, end, and optional metadata when imported via CSV.

7.2 Managing Projects via API

• GET /api/projects – list projects for the current organization.
• POST /api/projects – create or update a project:
  • If you provide an id, that record is overwritten.
  • If you omit id, a new UUID is generated.
• DELETE /api/projects?id=... – delete a project by ID.

8. Consultants (Resources)

• Consultants are stored per organization with key br_consultant:<orgId>:<id>.
• Typical fields:
  • name, email, role, grade, practices, location
  • Capacity per week, cost rate, skills, tags.
• Endpoints:
  • GET /api/consultants – list consultants and their projects.
  • POST /api/consultants – create/update a consultant by ID or email.
  • DELETE /api/consultants?id=... – remove a consultant.

9. Assignments & Planner View

Assignments link resources to projects (who is on which project, when, and at what allocation).

• Stored under keys: br_assignment:<orgId>:<assignmentId> or combined keys using project code + email + start date.
• Expected fields:
  • projectCode, resourceEmail
  • start, end
  • allocationPct and notes
• Endpoint:
  • GET /api/assignments – returns all assignments for the current org.

The Resource Planner view:

• Fetches /api/assignments and /api/projects.
• Displays each assignment with:
  • Project name (from project map or inline assignment field),
  • Consultant name,
  • Start and end dates,
  • Allocation percentage.
• If no assignments are found, a friendly “No assignments yet” message is shown.

10. Dashboard & Forecast

• The Dashboard view pulls:
  • /api/projects
  • /api/consultants
  • /api/forecast?weeks=4
• Key metrics displayed:
  • Total number of projects.
  • Total number of consultants.
  • Headline utilization percentage.
  • Number of “overloaded” weeks and idle periods based on simple utilisation logic.
• Quick actions:
  • Open Resource Planner.
  • Open Timeline view (placeholder).
  • Export projects as CSV via /api/export.

11. CSV Import from Excel

The Settings section includes a CSV import panel to load existing data from spreadsheets.

11.1 How to Import

1. Go to Settings in the sidebar.
2. Under Import from Excel / CSV:
   • Choose a type: Projects.csv, Resources.csv, or Assignments.csv.
   • Select a .csv file from your computer.
   • Optionally keep Dry run only checked to validate without saving.
3. Click Upload & Import.
4. Results appear in the log area:
   • Number of rows imported.
   • Any missing headers or row-level errors.
   • A sample of parsed rows.

11.2 Required Headers

For quick reference:

• Projects.csv: ProjectCode, ProjectName, ClientName, Practice, PMName, PMEmail, StartDate, EndDate, Status, Budget, Currency, Location, Tags, Notes
• Resources.csv: ResourceEmail, ResourceName, Role, Grade, Org, Practice, Location, CapacityPerWeek, CostRate, Currency, Skills, Tags, Notes
• Assignments.csv: ProjectCode, ResourceEmail, StartDate, EndDate, AllocationPct, Notes

12. Subscription & Billing (Stripe)

12.1 Plans

• Free
  • Good for trials and small teams.
  • May enforce soft limits in UI (e.g. team size) depending on your implementation.
• Starter
  • Backed by Stripe price ID price_1SY06ZKZUwnbGgM037sW4rR5.
  • Suggested price: 90 SGD/month.
• Professional
  • Backed by Stripe price ID price_1SY09cKZUwnbGgM0ru2KCElc.
  • Suggested price: 350 SGD/month.

12.2 Upgrading an Organization

1. On the Dashboard or Settings, click the upgrade button under the plan you want.
2. The frontend calls /api/create-checkout with the chosen plan.
3. A Stripe Checkout session is created, and the browser is redirected to Stripe.
4. After payment:
   • Stripe calls /api/stripe-webhook with subscription events.
   • The organization’s plan and licenseValid fields are updated accordingly.

12.3 Downgrades and Cancellations

• Subscription deleted:
  • The webhook logic can delete the organization and all related data for that customer.
• Payment failed:
  • The organization is downgraded to free with licenseValid = false.

13. Blue River AI Assistant

13.1 What the AI Knows

• Projects for the current organization.
• Consultants and their associated projects.
• Aggregate context built by /api/context.

13.2 Using the AI Panel

1. Click the floating AI button (bottom-right).
2. Type your question, e.g.:
   • "Which consultants are over-allocated in the next 4 weeks?"
   • "Summarize projects in the Data practice."
3. Click Ask AI.
4. The answer appears in the AI chat area using the configured Workers AI model.

13.3 Backend Behaviour

• The app calls /api/context to fetch current org projects and consultants.
• Then calls /api/assist with:
  • question – your text.
  • context – the structured org data.
• The Worker forwards this to @cf/meta/llama-3-8b-instruct via Workers AI and returns a concise answer.

14. Export & Reporting

• Export Projects to CSV:
  • From the dashboard, click Export CSV.
  • This triggers /api/export, returning a CSV file with key project fields: projectName, consultant, hours, practice, start, end.
• You can filter by practice using ?practice=... in the export URL if needed.

15. Health Check & Diagnostics

• GET /health returns a simple JSON: {"status":"ok","version":"4.0-enterprise"}.
• Use this endpoint for uptime checks, monitoring and verifying deployment.

16. Typical Troubleshooting Tips

• Cannot log in:
  • Confirm you signed up with the same email.
  • Check for trailing spaces in email or password fields.
• "Not logged in or no organization selected":
  • Your session may have expired – log in again.
  • Ensure at least one organization exists and is selected in the top bar.
• AI errors:
  • Verify the AI binding is correctly configured in wrangler.toml.
  • Check Workers AI limits or region availability.
• Stripe issues:
  • Ensure STRIPE_SECRET_KEY is set as a Worker secret.
  • Confirm the webhook endpoint URL is configured in your Stripe dashboard.
  • Check logs for any webhook parsing errors.

17. Deployment Notes

• Bind the following in your wrangler.toml:
  • KV namespace: BLUE_RIVER_ENT_KV
  • Workers AI binding: AI
  • Secret: STRIPE_SECRET_KEY
• Deploy using:
  • wrangler deploy
• After deployment:
  • Check /health is reachable.
  • Test signup, login and dashboard.