FAS Repository Map

This document maps each repository in the Frontend Application Split project to its purpose, key exports, and relationship to other repos.

Repository Overview

Repository	Type	Purpose	Key Exports / Features
api	Package	IC canister client utilities	`createActor`, `ApiResponse<T>`, `ERROR_CODES`, `checkServiceHealth`
auth	Package	Authentication context & hooks	`AuthProvider`, `useAuth`, `ProtectedRoute`, `AuthContextValue`
ui	Package	Shared UI components & Tailwind config	`Button`, `Card`, `Modal`, `ErrorBoundary`, `cn`, Tailwind base config
suite-template	Template	Base template for new suites	GitHub template repo -- use "Use this template"
think-tank-suite	Suite	Think Tank productivity app	Mission Control, Workspace, Chat, Fleet, Backlog, Capture, Settings
governance-suite	Suite	Governance & voting UI	Proposals, Voting, Discussions, Deep Links
marketing-suite	Suite	Public marketing site with SEO	Landing page, waitlist, i18n, pre-rendered HTML, sitemap
otter-camp-suite	Suite	Otter Camp game UI	Phaser.js game, character creation, multiplayer, combat
dao-suite	Suite	Member dashboard (DAO portal)	Dashboard, proposals, voting, treasury, membership, settings
dao-admin-suite	Suite	Admin dashboard with RBAC	KYC review, member management, governance oversight, treasury
.github (dot-github)	Infra	Reusable CI/CD workflows	`package-publish.yml`, `suite-deploy.yml`, `shared-test.yml`

Detailed Repository Descriptions

@hello-world-co-op/api

Clone path: ~/git/api/

IC canister client factory and response types. All canister communication goes through this package.

Directory	Purpose
`src/`	Source: createActor, ApiResponse, ErrorCodes, healthCheck
`tests/`	Vitest unit tests

Run locally: npm install && npm testPublish: Push tag v0.x.x -> triggers package-publish.yml

@hello-world-co-op/auth

Clone path: ~/git/auth/

Authentication provider, hooks, and route guards. Depends on @hello-world-co-op/api.

Directory	Purpose
`src/`	AuthProvider, useAuth, ProtectedRoute, token storage
`tests/`	Vitest unit tests

Run locally: npm install && npm testPublish: Push tag v0.x.x -> triggers package-publish.yml

@hello-world-co-op/ui

Clone path: ~/git/ui/

Shared UI component library built on Radix UI primitives with Tailwind CSS. Depends on @hello-world-co-op/auth.

Directory	Purpose
`src/components/`	Button, Card, Modal, Input, Select, ErrorBoundary, etc.
`src/utils/`	`cn()` class name utility
`tailwind.config.js`	Base Tailwind config that suites extend
`tests/`	Vitest + React Testing Library tests

Run locally: npm install && npm testPublish: Push tag v0.x.x -> triggers package-publish.yml

suite-template

Clone path: ~/git/suite-template/

GitHub template repository for creating new suites. Not published as a package.

File	Purpose
`README.md`	Template documentation
`USAGE.md`	Step-by-step new suite guide
`MIGRATION_GUIDE.md`	Guide for migrating existing suites
`TEMPLATE_CHECKLIST.md`	Post-creation checklist

Use: Click "Use this template" on GitHub, or git clone and reinitialize.

think-tank-suite

Clone path: ~/git/think-tank-suite/

The Think Tank productivity application. Largest suite with 4,642 tests.

Property	Value
Tests	4,642 unit
Canister ID	`wnfjk-biaaa-aaaao-a6dhq-cai`
Staging Domain	staging-think-tank.helloworlddao.com
Production Domain	think-tank.helloworlddao.com
Auth Pattern	Bridge (AuthProviderBridge)
Packages	`@hello-world-co-op/ui`, `auth`, `api`

Directory	Purpose
`src/pages/`	MissionControl, Workspace, Chat, Backlog, Fleet, Capture, Settings, Admin
`src/components/`	Suite-specific components (11 directories)
`src/services/`	API clients, canister service wrappers, apiHelpers.ts (re-exports from @hello-world-co-op/api)
`src/stores/`	Nanostores state management (auth, capture, workspace, etc.)
`src/hooks/`	Custom React hooks (useAuth bridges to shared interface)
`.github/workflows/`	ci.yml, deploy-staging.yml

Run locally: npm install && npm run dev (port 5174) Deploy: Push to main -> CI -> deploy to IC canister wnfjk-biaaa-aaaao-a6dhq-cai

governance-suite

Clone path: ~/git/governance-suite/

DAO governance and voting interface. 867 unit tests + 69 E2E tests.

Property	Value
Tests	867 unit, 69 E2E
Canister ID	`wkep6-mqaaa-aaaao-a6dha-cai`
Staging Domain	staging-governance.helloworlddao.com
Production Domain	governance.helloworlddao.com
Auth Pattern	Direct (nanostores, no bridge)
Packages	`@hello-world-co-op/ui` only

Directory	Purpose
`src/pages/`	ProposalsPage, VotingPage, DiscussionsPage, DiscussionDetailPage, ProposalDetailPage, MyVotesPage
`src/components/governance/`	VoteSelector, VoteConfirmationModal, VoteBreakdownBar, ProposalCard, etc.
`src/stores/`	Nanostores (authStore, proposalStore)
`e2e/`	Playwright E2E specs (voting, proposals, discussions, app)
`.github/workflows/`	ci.yml, deploy-staging.yml

Run locally: npm install && npm run dev (port 5174) Deploy: Push to main -> CI -> deploy to IC canister wkep6-mqaaa-aaaao-a6dha-cai

marketing-suite

Clone path: ~/git/marketing-suite/

Public marketing site with SEO pre-rendering. Standalone suite -- no auth dependency.

Property	Value
Tests	83 unit
Bundle Size	358KB
Canister ID	`d5fe6-hqaaa-aaaao-a6t5q-cai`
Staging Domain	staging.helloworlddao.com
Production Domain	www.helloworlddao.com
Auth Pattern	Standalone (no auth)
Packages	`@hello-world-co-op/ui` (UI only, no auth dependency)

Directory	Purpose
`src/components/`	HeroSection, AboutSection, LaunchContent, SEO, InterestForm, VerificationCodeForm, LanguageSelector
`src/pages/`	LaunchPage (landing), PrivacyPolicy
`scripts/`	prerender.ts (build-time HTML generation), generate-sitemap.ts
`src/utils/`	crypto.ts (AES-256-GCM), validation.ts (Zod), i18n.ts
`.github/workflows/`	ci.yml, deploy-staging.yml

Key features: SEO pre-rendering via ReactDOMServer.renderToString(), sitemap.xml generation, react-helmet-async, i18n (EN, ES, FR, PT), client-side PII encryption.

Run locally: npm install && npm run dev (port 5173) Deploy: Push to main -> CI -> deploy to IC canister d5fe6-hqaaa-aaaao-a6t5q-cai

otter-camp-suite

Clone path: ~/git/otter-camp-suite/

Otter Camp game UI built with Phaser.js. Standalone suite -- no shared packages.

Property	Value
Tests	2,115 unit, 7 E2E
Bundle Size	58KB initial (Phaser lazy-loaded: ~340KB)
Canister ID	`dzt3i-sqaaa-aaaao-a6uaa-cai`
Staging Domain	staging-ottercamp.helloworlddao.com
Production Domain	ottercamp.helloworlddao.com
Auth Pattern	Standalone (reads localStorage passively)
Packages	None (fully standalone)

Directory	Purpose
`src/game/scenes/`	BootScene, CharacterCreation, CampHub, Combat
`src/game/entities/`	Otter, RemoteOtter, NPC, Building, Fragment
`src/game/systems/`	MultiplayerSystem, CombatSystem, VotingSystem, etc.
`src/game/services/`	Game services (voting, treasury, combat)
`src/game/ui/`	Phaser UI overlays, minimap, HUD
`src/game/bridge/`	GameBridge React-Phaser integration
`.github/workflows/`	ci.yml, deploy-staging.yml

Key features: Phaser.js extracted to standalone chunk, character creation, camp exploration, multiplayer via WebSocket (oracle-bridge), combat system, tutorial system.

Run locally: npm install && npm run dev (port 5176) Deploy: Push to main -> CI -> deploy to IC canister dzt3i-sqaaa-aaaao-a6uaa-cai

dao-suite

Clone path: ~/git/dao-suite/

DAO member dashboard. Auth-integrated suite using bridge pattern.

Property	Value
Tests	806 unit
Bundle Size	348KB
Canister ID	`d6s54-7iaaa-aaaao-a6uaq-cai`
Staging Domain	staging-portal.helloworlddao.com
Production Domain	portal.helloworlddao.com
Auth Pattern	Bridge (AuthProviderBridge + cookie SSO)
Packages	`@hello-world-co-op/ui`, `auth`, `api`

Directory	Purpose
`src/pages/`	Dashboard, Proposals, Voting, Membership, Treasury, TokenBalance, Escrow, MemberDirectory, Settings
`src/features/`	proposal-creation (AI-assisted), proposals, voting, settings
`src/components/`	ProtectedRoute, ErrorBoundary, Toast, UI bridge components
`src/stores/`	Nanostores atoms for state management
`src/services/`	API and canister service clients
`.github/workflows/`	ci.yml, deploy-staging.yml

Key features: Cookie-based SSO with localStorage bridge, ProtectedRoute guard, AI-assisted proposal creation (Think Tank).

Run locally: npm install && npm run dev (port 5174). Requires oracle-bridge running for auth. Deploy: Push to main -> CI -> deploy to IC canister d6s54-7iaaa-aaaao-a6uaq-cai

dao-admin-suite

Clone path: ~/git/dao-admin-suite/

Admin dashboard with RBAC. Auth-integrated suite using bridge pattern.

Property	Value
Tests	115 unit
Bundle Size	93KB
Canister ID	`dxrwa-jaaaa-aaaao-a6uba-cai`
Staging Domain	staging-admin.helloworlddao.com
Production Domain	admin.helloworlddao.com
Auth Pattern	Bridge (AuthProviderBridge + AdminGuard)
Packages	`@hello-world-co-op/ui`, `auth`, `api`

Directory	Purpose
`src/pages/`	AdminDashboard, KYCManagement, MemberManagement, GovernanceOversight, TreasuryManagement, SystemMonitoring, ContentModeration, LoginRedirect
`src/components/admin/`	KYCReviewDashboard, KYCReviewDetail, KYCReviewPage
`src/utils/`	validateReturnUrl.ts (admin-specific open redirect prevention)
`src/hooks/`	useAdminAuth.ts
`.github/workflows/`	ci.yml, deploy-staging.yml

Key features: AdminGuard RBAC component (FAS-7.2 deferred to bl-007), admin-specific validateReturnUrl, KYC review workflow with SLA indicators, desktop-only design.

Run locally: npm install && npm run dev (port 5176). Requires oracle-bridge running for auth. Deploy: Push to main -> CI -> deploy to IC canister dxrwa-jaaaa-aaaao-a6uba-cai

.github (dot-github)

Clone path: ~/git/dot-github/

Organization-level GitHub configuration with reusable CI/CD workflows.

Workflow	Purpose	Triggered By
`package-publish.yml`	Build, test, publish npm package to GitHub Packages	Tag push `v*`
`suite-deploy.yml`	Build, test, deploy suite to IC canister	Called by suite workflows
`shared-test.yml`	Shared test runner with coverage	Called by package workflows

Also contains the Local Development Workflow documentation (npm link, file references, cross-package dev).

"Where Do I Make Changes?" Quick Reference

I want to...	Change in repo
Fix a shared UI component (Button, Card, etc.)	`ui`
Update auth logic (login, session, tokens)	`auth`
Change canister client factory or response types	`api`
Add a new Think Tank page or feature	`think-tank-suite`
Add a new governance page or voting feature	`governance-suite`
Update marketing site content or SEO	`marketing-suite`
Update game mechanics or Phaser.js code	`otter-camp-suite`
Add member dashboard features (proposals, treasury)	`dao-suite`
Add admin features (KYC, monitoring, moderation)	`dao-admin-suite`
Modify CI/CD pipeline for all packages	`dot-github` (.github repo)
Create a brand new suite	Fork from `suite-template`
Update this documentation	`docs`

Understanding Package Dependencies

You can use standard npm tooling to inspect package relationships:

List installed packages

bash

# In any suite directory, show installed @hello-world-co-op packages
npm list @hello-world-co-op/*

Example output (from dao-suite):

dao-suite@0.1.0
├── @hello-world-co-op/api@0.1.0
├── @hello-world-co-op/auth@0.1.0
└── @hello-world-co-op/ui@0.1.0

View package dependencies

bash

# See what a package depends on
npm view @hello-world-co-op/ui dependencies --registry=https://npm.pkg.github.com

Example output:

{
  '@hello-world-co-op/auth': '^0.1.0',
  'tailwindcss': '^3.0.0',
  '@radix-ui/react-dialog': '^1.0.0'
}

Check for outdated packages

bash

# Show available updates
npm outdated @hello-world-co-op/*

Example output:

Package                      Current  Wanted  Latest
@hello-world-co-op/api       0.1.0    0.1.0   0.1.0
@hello-world-co-op/auth      0.1.0    0.1.0   0.1.0
@hello-world-co-op/ui        0.1.0    0.1.0   0.1.0

Inspect package.json

Each suite's package.json dependencies section shows which shared packages it consumes:

json

{
  "dependencies": {
    "@hello-world-co-op/api": "^0.1.0",
    "@hello-world-co-op/auth": "^0.1.0",
    "@hello-world-co-op/ui": "^0.1.0"
  }
}

Check Published Versions

Visit the GitHub Packages UI for the organization: https://github.com/orgs/Hello-World-Co-Op/packages

Each package page shows all published versions, download counts, and linked repositories.

Architecture Overview -- How packages and suites fit together
Local Setup Guide -- Getting started
Suite Creation Guide -- Creating new suites from template
Troubleshooting -- Common issues
Cross-Suite Auth Debugging -- Diagnosing SSO issues
Rollback Procedures -- Suite-specific rollback steps

FAS Repository Map ​

Repository Overview ​

Detailed Repository Descriptions ​

@hello-world-co-op/api ​

@hello-world-co-op/auth ​

@hello-world-co-op/ui ​

suite-template ​

think-tank-suite ​

governance-suite ​

marketing-suite ​

otter-camp-suite ​

dao-suite ​

dao-admin-suite ​

.github (dot-github) ​

"Where Do I Make Changes?" Quick Reference ​

Understanding Package Dependencies ​

List installed packages ​

View package dependencies ​

Check for outdated packages ​

Inspect package.json ​

Check Published Versions ​

Related Documentation ​

FAS Repository Map

Repository Overview

Detailed Repository Descriptions

@hello-world-co-op/api

@hello-world-co-op/auth

@hello-world-co-op/ui

suite-template

think-tank-suite

governance-suite

marketing-suite

otter-camp-suite

dao-suite

dao-admin-suite

.github (dot-github)

"Where Do I Make Changes?" Quick Reference

Understanding Package Dependencies

List installed packages

View package dependencies

Check for outdated packages

Inspect package.json

Check Published Versions

Related Documentation