Project Architecture Overview

This document provides a high-level overview of the architecture and folder structure of the codebase. It is intended to help new developers quickly understand how the project is organized and where to find key functionality.

Architecture

Repository Structure

The SeedStart platform is a monorepo containing frontend, backend, and shared code:

Directory	Purpose
web/	Frontend UI (React/Vite), deployed to Firebase Hosting
functions/	Firebase Cloud Functions (backend), deployed to Cloud Run
shared/	Shared TypeScript types used by both web and functions
docs/	Project documentation

Data Access

• Frontend (web/): Accesses Firestore directly using the Firebase SDK. Firestore security rules enforce access control.
• Backend (functions/): Cloud Functions handle background tasks, scheduled jobs, OAuth callbacks, API endpoints, and push notifications. Functions are deployed to Firebase Functions (v2, running on Cloud Run).
• Shared (shared/): TypeScript types and interfaces used by both frontend and backend for type safety.

Package Management

The project uses pnpm with workspace configuration for efficient monorepo dependency management.

---

Top-Level Structure

seedsite/
├── web/                     # Frontend application
│   ├── src/
│   │   ├── components/      # Reusable UI components
│   │   ├── contexts/        # React context providers
│   │   ├── hooks/           # Custom React hooks
│   │   ├── pages/           # Route-level components
│   │   ├── services/        # Business logic and Firebase
│   │   ├── types/           # TypeScript types (legacy, migrating to shared/)
│   │   └── utils/           # Utility functions
│   ├── public/              # Static assets
│   └── package.json
├── functions/               # Cloud Functions (backend)
│   ├── src/
│   │   ├── api/             # REST API endpoints (/api/v1)
│   │   ├── auth/            # Auth-related functions
│   │   ├── calendar/        # Google Calendar integration
│   │   ├── discord/         # Discord integration
│   │   ├── github/          # GitHub integration
│   │   ├── middleware/      # Express middleware
│   │   ├── routes/          # API route handlers
│   │   ├── services/        # Business logic
│   │   └── index.ts         # Function exports
│   ├── docs/                # API documentation
│   └── package.json
├── shared/                  # Shared types and utilities
│   ├── src/types/           # TypeScript types used by web and functions
│   └── package.json
├── docs/                    # Project documentation
├── .github/workflows/       # CI/CD workflows
├── package.json             # Root workspace config
├── pnpm-workspace.yaml      # pnpm workspace config
└── firebase.json            # Firebase project config

---

Folder Responsibilities

Frontend (web/)

web/src/components/

• Purpose: Reusable UI components, grouped by domain or function.
• Subfolders:
  • user/ — User-related UI (badges, dialogs, avatars, etc.)
  • form/ — Form and input components
  • display/ — Display-only components
  • org/ — Organization-related UI
  • layout/, TopBar/, etc. — Layout and navigation

web/src/pages/

• Purpose: Route-level components, each representing a page or major view.
• Examples: Org/, PitchDeck/, Meeting/, Tasks/, Integrations/, etc.

web/src/contexts/

• Purpose: React context providers for global state (auth, user, org, etc.)

web/src/hooks/

• Purpose: Custom React hooks for encapsulating logic (auth, team management, etc.)

web/src/services/

• Purpose: Service layer for business logic, Firestore references, and Firebase configuration.
• Key files:
  • firestoreRefs.ts — Centralized, type-safe Firestore references
  • firebaseConfig.ts — Firebase initialization

web/src/types/

• Purpose: TypeScript type definitions (legacy, being migrated to shared/)

web/src/utils/

• Purpose: Utility functions and helpers

Backend (functions/)

functions/src/api/

• Purpose: Combined API service serving REST endpoints and OAuth callbacks
• Key file: index.ts — Express app with /api/v1 router

functions/src/routes/

• Purpose: API route handlers for different resources
• Examples: orgs.ts, members.ts, documents.ts, calendar.ts, etc.

functions/src/middleware/

• Purpose: Express middleware for auth, pagination, error handling, etc.

functions/src/services/

• Purpose: Business logic, permissions, utilities

functions/src/calendar/, functions/src/github/, functions/src/discord/

• Purpose: Integration-specific cloud functions and utilities

Shared (shared/)

shared/src/types/

• Purpose: TypeScript types shared between frontend and backend
• Examples: organization.ts, member.ts, document.ts, onboarding.ts, etc.

---

Key Concepts

• Centralized Firestore Refs: All Firestore access is routed through src/services/firestoreRefs.ts for type safety and maintainability.
• Type Safety: All data models are defined in src/types/ and used throughout the app.
• Component Grouping: UI components are grouped by domain (user, form, display, org, etc.) for clarity and scalability.
• Feature Folders: Pages and services are organized by feature (e.g., Org, PitchDeck, Meeting) to keep related logic together.
• State Management: Contexts and stores are used for global and feature state.

---

How to Add a New Feature

Frontend Feature

1. Create a new folder in web/src/pages/ for the route/view.
2. Add any reusable UI to web/src/components/ (grouped by domain if possible).
3. Add business logic to web/src/services/ if needed.
4. Define types in shared/src/types/ for any new data models.
5. Add state management in web/src/contexts/ if the feature needs global state.

Backend Feature (API Endpoint)

1. Create a new route file in functions/src/routes/ (e.g., myresource.ts).
2. Mount the router in functions/src/api/index.ts under the v1Router.
3. Define shared types in shared/src/types/ for request/response models.
4. Add business logic to functions/src/services/ if needed.
5. Update functions/docs/API.md with endpoint documentation.

Cloud Function (Non-API)

1. Create function in appropriate folder (functions/src/calendar/, functions/src/github/, etc.).
2. Export from functions/src/index.ts.
3. Add required secrets to GitHub Actions if needed.

---

Key Technical Decisions

• Monorepo: All code in one repo for easier refactoring and shared types
• pnpm workspaces: Efficient dependency management with workspace protocol
• Shared types: TypeScript types in shared/ ensure type safety across frontend and backend
• Centralized Firestore refs: All Firestore access in frontend uses web/src/services/firestoreRefs.ts
• API consolidation: REST endpoints consolidated under the api cloud function (not separate functions)
• Firebase Functions v2: Backend runs on Cloud Run for better performance and scaling

Deployment

• Frontend: Deployed to Firebase Hosting on push to main (dev) or tag (prod)
• Functions: Deployed to Firebase Functions (Cloud Run) on push to main (dev) or tag (prod)
• CI/CD: GitHub Actions workflows in .github/workflows/

---

For more details, see the README, DEPLOYMENT.md, or ask a maintainer!