AeThex-Corporation/aethex-forge
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
aethex-forge/docs/AXIOM-MODEL-PHASE1-SCOPE.md
Builder.io e141e68ef4 Prettier format pending files
2025-11-17 02:27:28 +00:00

310 lines
13 KiB
Markdown
Raw Permalink Blame History

# Axiom Model: Phase 1 Code Migration Scope
## Moving Identity from aethex.dev (Vercel) to aethex.foundation (Replit)
**Status:** CRITICAL P0 (Blocks NEXUS & FOUNDATION work)
**Date:** 2025-11-16
**Objective:** Copy all auth/identity code from Corp (aethex.dev) to Guardian (aethex.foundation)
---
## 1. PAGES TO COPY
### Authentication & Onboarding Pages
| File | Purpose | Notes |
| ------------------------------------- | ----------------------------------- | ------------------------------------------- |
| `code/client/pages/Login.tsx` | Login UI + Discord OAuth button | Copy as-is; validate Discord button routing |
| `code/client/pages/Signup.tsx` | (if exists) User registration | Copy if present |
| `code/client/pages/Onboarding.tsx` | Realm/arm selection, profile setup | Copy all onboarding flow |
| `code/client/pages/DiscordVerify.tsx` | Verification code entry for linking | Copy verification flow |
### Profile & Settings Pages
| File | Purpose | Notes |
| --------------------------------- | -------------------------------------- | --------------------------- |
| `code/client/pages/Profile.tsx` | (or Dashboard) User profile view | Copy public profile viewing |
| `code/client/pages/Dashboard.tsx` | User dashboard + OAuthConnections | Copy OAuth linking UI |
| `code/client/pages/settings/*` | Profile settings, password reset, etc. | Copy all settings pages |
### Passport Pages
| File | Purpose | Notes |
| ----------------------------------------- | --------------------------------- | ------------------------------------ |
| `code/client/pages/SubdomainPassport.tsx` | Creator passport for \*.aethex.me | Copy; will fetch from Foundation API |
---
## 2. CONTEXTS & STATE MANAGEMENT
| File | Purpose | Dependencies |
| ------------------------------------------------- | ----------------------------------------------- | ------------------------------------ |
| `code/client/contexts/AuthContext.tsx` | Central auth state, loginProvider, linkProvider | Depends on Supabase client |
| `code/client/contexts/DiscordActivityContext.tsx` | Discord Activity SDK state | Optional; copy if Activity is needed |
| `code/client/contexts/ThemeContext.tsx` | Theme switching | Dependency; copy |
---
## 3. COMPONENTS TO COPY
### Auth & OAuth Components
| File | Purpose |
| --------------------------------------------------------- | ------------------------------------------------- |
| `code/client/components/settings/OAuthConnections.tsx` | OAuth provider cards (Discord, etc.) |
| `code/client/components/admin/AdminDiscordManagement.tsx` | Admin UI for role mappings (optional for Phase 1) |
### Profile & Passport Components
| File | Purpose |
| ----------------------------------------------------- | ------------------------ |
| `code/client/components/passport/PassportSummary.tsx` | Renders creator passport |
| `code/client/components/ErrorBoundary.tsx` | Error handling |
| `code/client/components/LoadingScreen.tsx` | Loading UI |
| `code/client/components/Layout.tsx` | App layout & header |
### Shared UI Components
| Directory | Purpose |
| ----------------------------- | --------------------------------------- |
| `code/client/components/ui/*` | All Radix UI & design system components |
---
## 4. API ENDPOINTS & SERVERLESS FUNCTIONS TO COPY
### Discord OAuth Endpoints
| File | Endpoint | Purpose |
| ------------------------------------ | --------------------------------- | ---------------------------------- |
| `code/api/discord/oauth/start.ts` | `GET /api/discord/oauth/start` | Redirect to Discord authorization |
| `code/api/discord/oauth/callback.ts` | `GET /api/discord/oauth/callback` | Handle Discord callback, link user |
| `code/api/discord/verify-code.ts` | `POST /api/discord/verify-code` | Verify 6-digit code for linking |
| `code/api/discord/link.ts` | `POST /api/discord/link` | Link Discord account by code |
| `code/api/discord/sync-roles.ts` | `POST /api/discord/sync-roles` | Assign Discord roles after linking |
### Profile & Auth Endpoints
| File | Endpoint | Purpose |
| ---------------------------- | -------------------------- | ------------------------------------------ |
| `code/api/profile/ensure.ts` | `POST /api/profile/ensure` | Create or ensure user profile exists |
| `code/api/user/*` | Various | User data endpoints (review for auth deps) |
### Passport Endpoints
| File | Endpoint | Purpose |
| ------------------------------------------- | --------------------------------------- | ------------------------- |
| `code/api/passport/subdomain/[username].ts` | `GET /api/passport/subdomain/:username` | Creator passport JSON API |
| `code/api/passport/project/[slug].ts` | `GET /api/passport/project/:slug` | Project passport JSON API |
---
## 5. DATABASE MIGRATIONS TO COPY
| File | Purpose |
| --------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `code/supabase/migrations/20250107_add_discord_integration.sql` | Discord tables (discord_links, discord_verifications, discord_role_mappings) |
| All other user/auth-related migrations | Copy all identity-related schema |
**Supabase Tables Required:**
- `user_profiles`
- `user_auth_identities`
- `discord_links`
- `discord_verifications`
- `discord_role_mappings`
---
## 6. LIBRARIES & DEPENDENCIES
### Required npm packages (verify in aethex.dev package.json)
```json
{
"@supabase/supabase-js": "^2.x",
"@discord/embedded-app-sdk": "^2.x",
"react-router-dom": "^6.x",
"react-hook-form": "^7.x",
"zod": "^3.x",
"next-themes": "^0.3.x",
"@radix-ui/*": "latest",
"lucide-react": "latest",
"sonner": "^1.x",
"discord.js": "^14.x (if bot integration needed)"
}
```
### Environment Variables Needed
```
VITE_SUPABASE_URL=https://kmdeisowhtsalsekkzqd.supabase.co
VITE_SUPABASE_ANON_KEY=sb_publishable_...
SUPABASE_SERVICE_ROLE=eyJhbGc...
DISCORD_CLIENT_ID=578971245454950421
DISCORD_CLIENT_SECRET=JKlilGzcTWgfmt2wEqiHO8wpCel5VEji
DISCORD_BOT_TOKEN=NTc4OTcx...
VITE_API_BASE=https://aethex.foundation (after switchover)
```
---
## 7. CRITICAL ADAPTATIONS FOR REPLIT TARGET
| Current (aethex.dev) | Needed for aethex.foundation |
| ------------------------------------------ | ------------------------------------------- |
| Vercel serverless functions (`code/api/*`) | Express or Remix server endpoints on Replit |
| `VITE_API_BASE=https://aethex.dev` | `VITE_API_BASE=https://aethex.foundation` |
| Vite + React on Vercel | Vite + React on Replit (same) |
| Uses Vercel environment variables | Use Replit Secrets or .env |
### Key Refactoring Points
1. **API Endpoints:** Vercel's `/api/*` files may need conversion to Express routes in `code/server/index.ts` or equivalent Replit server.
2. **Base URLs:** Update all `VITE_API_BASE` references to point to `aethex.foundation` instead of `aethex.dev`.
3. **OAuth Redirect URIs:** Update Discord OAuth app to use `aethex.foundation` callback URL.
4. **CORS:** Ensure Foundation server allows requests from Corp domain (`aethex.dev`).
---
## 8. NEW SSO ENDPOINTS TO BUILD (Foundation)
After copying existing code, build 3 new OAuth 2.0 endpoints on aethex.foundation:
### 1. `/authorize` (Foundation SSO Authorization)
**Purpose:** Initiate login flow for external apps (aethex.dev)
```
GET /authorize?client_id=AETHEX_DEV&redirect_uri=https://aethex.dev/auth/callback&state=xyz
```
**Response:** Redirect user to `/login` with state preserved
### 2. `/token` (Foundation SSO Token Exchange)
**Purpose:** Exchange auth code for JWT token
```
POST /token
{
"grant_type": "authorization_code",
"code": "AUTH_CODE",
"client_id": "AETHEX_DEV",
"client_secret": "SECRET"
}
Returns:
{
"access_token": "JWT...",
"token_type": "Bearer",
"expires_in": 3600,
"user": { id, email, name, avatar_url, ... }
}
```
### 3. `/userinfo` (Foundation SSO User Info)
**Purpose:** Fetch current logged-in user info (used by aethex.dev after login)
```
GET /userinfo
Authorization: Bearer JWT_TOKEN
Returns:
{
"id": "USER_ID",
"email": "user@example.com",
"username": "username",
"avatar_url": "...",
"user_type": "creator",
"linked_providers": ["discord", "google"],
...
}
```
---
## 9. MIGRATION CHECKLIST
### Before Starting Phase 1
- [ ] Verify all auth code is in `code/client/pages/` and `code/api/discord/*`
- [ ] List all custom hooks used in auth flow (use-toast, etc.)
- [ ] Document all Supabase queries used for auth
- [ ] Get list of all environment variables currently in use
- [ ] Create a "mirror" directory structure on aethex.foundation (Replit)
### During Phase 1
- [ ] Copy all page files (Login, Signup, Onboarding, Dashboard, etc.)
- [ ] Copy all context files (AuthContext, DiscordActivityContext, ThemeContext)
- [ ] Copy all component files (OAuthConnections, PassportSummary, etc.)
- [ ] Copy all API endpoint files (discord/oauth/_, profile/ensure.ts, passport/_)
- [ ] Copy all Supabase migrations
- [ ] Copy tailwind.config.js and global.css for styling
- [ ] Adapt all import paths for new directory structure
- [ ] Update all `VITE_API_BASE` references
- [ ] Update Discord OAuth app redirect URIs
- [ ] Set up environment variables on Replit
### Testing Phase 1
- [ ] Can users log in via Discord on aethex.foundation?
- [ ] Can users view their profile?
- [ ] Can users link additional OAuth providers?
- [ ] Can users access their passport?
- [ ] Are Supabase queries working correctly?
- [ ] Are Discord OAuth callbacks returning correct data?
---
## 10. SUCCESS CRITERIA FOR PHASE 1
✅ All auth pages render correctly on aethex.foundation
✅ Users can log in via Discord on aethex.foundation
✅ Users can link additional accounts (Google, etc.)
✅ Passports display correctly
✅ All OAuth callbacks complete without errors
✅ Supabase access is working (read/write to user_profiles)
✅ Code is ready for Phase 2 (permission migration)
---
## 11. ESTIMATED EFFORT
| Task | Estimate |
| -------------------------- | --------------- |
| Audit & document auth code | 2-3 hours |
| Copy & adapt page files | 4-6 hours |
| Copy & adapt API endpoints | 3-4 hours |
| Fix imports & dependencies | 2-3 hours |
| Test login flow | 2-3 hours |
| Build SSO endpoints | 4-6 hours |
| **Total Phase 1** | **17-25 hours** |
---
## 12. BLOCKERS & RISKS
**Risk 1:** API endpoints on Vercel may not work on Replit without refactoring
→ Mitigation: Convert to Express routes on Replit server
**Risk 2:** Environment variable names differ between Vercel and Replit
→ Mitigation: Use consistent naming convention
**Risk 3:** Supabase RLS policies may prevent new app from writing to tables
→ Mitigation: Phase 2 handles permission migration
**Risk 4:** Discord OAuth app may not accept aethex.foundation as redirect URI
→ Mitigation: Update Discord app settings before testing
---
## Next Steps
1. **Review & Approve Scope:** Confirm this list is complete
2. **Set up Replit Structure:** Create mirrored directories on aethex.foundation
3. **Start Code Copy:** Begin with pages, then contexts, then components
4. **Adapt & Test:** Fix imports, test each piece as copied
5. **Proceed to Phase 2:** Once Phase 1 is solid, move to database permission migration
Reference in a new issue View git blame Copy permalink