180 lines
10 KiB
JSON
180 lines
10 KiB
JSON
{
|
|
"project": "aethex-forge",
|
|
"generated_at": "2025-11-16T00:00:00Z",
|
|
"overview": {
|
|
"description": "Comprehensive export of the Foundation site: frontend routes, components, server endpoints, Supabase schema references, Discord integration, build and deployment details.",
|
|
"root": "/",
|
|
"notes": "This file describes site structure, code locations, and deployment guidance. It references files present in the repository under 'code/'."
|
|
},
|
|
"frontend": {
|
|
"framework": "Vite + React",
|
|
"entry": "code/client/main.tsx",
|
|
"app_root": "code/client/App.tsx",
|
|
"pages_dir": "code/client/pages",
|
|
"pages": [
|
|
"code/client/pages/Index.tsx",
|
|
"code/client/pages/Login.tsx",
|
|
"code/client/pages/DiscordVerify.tsx",
|
|
"code/client/pages/Dashboard.tsx",
|
|
"code/client/pages/Activity.tsx",
|
|
"code/client/pages/Onboarding.tsx",
|
|
"code/client/pages/Admin.tsx",
|
|
"code/client/pages/404.tsx",
|
|
"code/client/pages/About.tsx",
|
|
"code/client/pages/creators/CreatorProfile.tsx",
|
|
"code/client/pages/docs/DocsOverview.tsx",
|
|
"code/client/pages/docs/DocsTutorials.tsx"
|
|
],
|
|
"routes_and_expected_urls": {
|
|
"/": "Index (code/client/pages/Index.tsx)",
|
|
"/login": "Login (code/client/pages/Login.tsx)",
|
|
"/dashboard": "Dashboard (code/client/pages/Dashboard.tsx)",
|
|
"/activity": "Discord Activity SPA (code/client/pages/Activity.tsx)",
|
|
"/onboarding": "Onboarding (code/client/pages/Onboarding.tsx)",
|
|
"/profile/:username": "Creator Profile (code/client/pages/creators/CreatorProfile.tsx)",
|
|
"/profile/link-discord": "Discord verification (code/client/pages/DiscordVerify.tsx)",
|
|
"/docs/*": "Docs pages (code/client/pages/docs/*)",
|
|
"subdomain passports (example: mrpiglr.aethex.me)": "Handled by client SubdomainPassport component (code/client/pages/SubdomainPassport.tsx) which fetches API: /api/passport/subdomain-data/:username"
|
|
},
|
|
"components_highlights": [
|
|
"code/client/components/Layout.tsx - app layout, header, nav",
|
|
"code/client/components/ui/* - shared UI primitives (accordion, alert, toast, loading)",
|
|
"code/client/components/passport/PassportSummary.tsx - renders passport summary",
|
|
"code/client/components/settings/OAuthConnections.tsx - OAuth providers UI (Discord etc.)",
|
|
"code/client/components/admin/AdminDiscordManagement.tsx - admin UI for discord role mappings",
|
|
"code/client/components/blog/* and docs components under code/client/components/docs"
|
|
],
|
|
"static_assets": "code/public (discord-manifest.json, placeholder.svg, robots.txt, site.webmanifest, etc.)"
|
|
},
|
|
"client_integration_points": {
|
|
"AuthContext": "code/client/contexts/AuthContext.tsx (central auth state, linkProvider('discord') flow)",
|
|
"DiscordActivityContext": "code/client/contexts/DiscordActivityContext.tsx (Activity SDK integration)",
|
|
"api_helpers": "code/client/api/* (client-side API wrappers)"
|
|
},
|
|
"api_and_server": {
|
|
"server_framework": "Express mounted into Vite dev middleware and built as a Node server",
|
|
"express_entry": "code/server/index.ts",
|
|
"server_build_entry": "code/server/node-build.ts (production entry)",
|
|
"server_mount_in_dev": "code/vite.config.ts -> expressPlugin loads createServer() from code/server/index.ts",
|
|
"server_routes_summary": {
|
|
"/api/passport/subdomain-data/:username": "Returns JSON for creator passport (code/server/index.ts)",
|
|
"/api/passport/project-data/:projectSlug": "Returns JSON for project passport (code/server/index.ts)",
|
|
"Discord OAuth and linking endpoints (server or api/*):": [
|
|
"code/api/discord/oauth/start.ts - OAuth start redirect",
|
|
"code/api/discord/oauth/callback.ts - OAuth callback handler",
|
|
"code/api/discord/link.ts - Link via verification code",
|
|
"code/api/discord/verify-code.ts - Verify posted code",
|
|
"code/api/discord/activity-auth.ts - Activity token verification",
|
|
"code/api/discord/sync-roles.ts - Role sync endpoint",
|
|
"code/api/discord/admin-register-commands.ts - (admin command registration)"
|
|
],
|
|
"Other serverless APIs (Vercel-style) under code/api": "Many endpoints for achievements, profile/ensure, feed, blog, nexus, etc. See code/api/**/*"
|
|
},
|
|
"server_notes": "Production server serves dist/spa static files from dist/server and runs the Express app (node dist/server/production.mjs). In dev the Express app is mounted into Vite dev server.",
|
|
"server_files": ["code/server/index.ts","code/server/supabase.ts","code/server/node-build.ts"]
|
|
},
|
|
"supabase_and_db": {
|
|
"primary": "VITE_SUPABASE_URL (https://kmdeisowhtsalsekkzqd.supabase.co) and alias SUPABASE_URL (https://supabase.aethex.tech)",
|
|
"service_role": "SUPABASE_SERVICE_ROLE (server-side service role token)",
|
|
"migrations_dir": "code/supabase/migrations",
|
|
"relevant_migrations": [
|
|
"code/supabase/migrations/20250107_add_discord_integration.sql",
|
|
"code/supabase/migrations/202407090001_create_applications.sql",
|
|
"... other migrations under code/supabase/migrations"
|
|
],
|
|
"important_tables": [
|
|
"user_profiles",
|
|
"user_achievements",
|
|
"user_interests",
|
|
"user_auth_identities",
|
|
"discord_links",
|
|
"discord_verifications",
|
|
"discord_role_mappings",
|
|
"applications, invites, other project-specific tables"
|
|
],
|
|
"db_access_from_server": "code/api/_supabase.ts (serverless functions) and code/server/supabase.ts (Express server) initialize admin clients using SUPABASE_SERVICE_ROLE"
|
|
},
|
|
"discord_integration": {
|
|
"bot_code": "code/discord-bot/bot.js and commands under code/discord-bot/commands/*.js",
|
|
"oauth": {
|
|
"start": "code/api/discord/oauth/start.ts",
|
|
"callback": "code/api/discord/oauth/callback.ts",
|
|
"redirect_uri_env": "DISCORD_REDIRECT_URI (set to production callback URL)"
|
|
},
|
|
"activity": {
|
|
"manifest": "code/public/discord-manifest.json",
|
|
"activity_auth_endpoint": "code/api/discord/activity-auth.ts",
|
|
"client_integration": "code/client/contexts/DiscordActivityContext.tsx and code/client/pages/Activity.tsx"
|
|
},
|
|
"linking_flow": "user clicks 'Link Discord' -> linkProvider('discord') -> /api/discord/oauth/start -> OAuth -> /api/discord/oauth/callback -> backend saves discord_link (discord_links table) -> triggers role sync",
|
|
"slash_commands": "registered via discord-bot scripts or admin API (code/discord-bot/scripts/register-commands.js / code/api/discord/admin-register-commands.ts)",
|
|
"health_checks": "code/client/lib/discord-bot-status.ts polls bot health endpoints (bot health API located in code/server/index.ts or code/api/discord/bot-health.ts)"
|
|
},
|
|
"design_and_layout": {
|
|
"design_system": "Tailwind CSS + Lucide icons + Radix UI primitives (see dependencies)",
|
|
"global_styles": "code/client/global.css",
|
|
"layout_component": "code/client/components/Layout.tsx",
|
|
"passport_ui": "code/client/components/passport/PassportSummary.tsx",
|
|
"theme_and_switcher": "code/client/components/ThemeToggle and ArmSwitcher in code/client/components/ArmSwitcher.tsx",
|
|
"ui_primitives": "code/client/components/ui/* (accordion, alert, toast, loading screen)"
|
|
},
|
|
"build_and_scripts": {
|
|
"dev": "npm run dev -> vite (code/vite.config.ts mounts Express in dev)",
|
|
"build_flow": "npm run build -> build:api (node build-api.js), build:client (vite build), build:server (vite build --config vite.config.server.ts)",
|
|
"start_production": "npm start -> node dist/server/production.mjs",
|
|
"docker": "code/Dockerfile (added for Railway); builds and runs the production server exposing PORT (3000)",
|
|
"important_files": ["code/package.json","code/vite.config.server.ts","code/vite.config.ts","code/build-api.js","code/Dockerfile"]
|
|
},
|
|
"deployment_and_hosts": {
|
|
"current_hosts": {
|
|
"vercel": "Frontend + serverless functions (code/api/*) can be deployed to Vercel",
|
|
"fly_io": "Previously used to host Express server; domain example given in conversation",
|
|
"railway": "Configured (code/railway.json + Dockerfile) as recommended unified host for Express + Bot + Frontend"
|
|
},
|
|
"dns_notes": "Subdomain passports require wildcard DNS (*.aethex.me) pointing to the host running Express server. If Express is on Railway/Fly, update DNS accordingly. Vercel cannot serve arbitrary wildcard subdomain server routes unless serverless functions handle them.",
|
|
"recommended_setup": "Keep frontend on Vercel if desired; deploy Express + Discord bot to Railway or Fly; point wildcard DNS to that host. Alternatively deploy everything to Railway for single-host simplicity."
|
|
},
|
|
"environment_variables": {
|
|
"required_keys": [
|
|
"VITE_SUPABASE_URL",
|
|
"VITE_SUPABASE_ANON_KEY",
|
|
"SUPABASE_SERVICE_ROLE",
|
|
"SUPABASE_URL",
|
|
"DISCORD_CLIENT_ID",
|
|
"DISCORD_CLIENT_SECRET",
|
|
"DISCORD_BOT_TOKEN",
|
|
"DISCORD_PUBLIC_KEY",
|
|
"DISCORD_REDIRECT_URI",
|
|
"VITE_API_BASE",
|
|
"SMTP_HOST",
|
|
"SMTP_PORT",
|
|
"SMTP_USER",
|
|
"SMTP_PASSWORD",
|
|
"VITE_GHOST_API_URL",
|
|
"GHOST_ADMIN_API_KEY",
|
|
"FOURTHWALL_API_EMAIL",
|
|
"FOURTHWALL_API_PASSWORD"
|
|
],
|
|
"notes": "Do not commit secrets to source. Use Railway/Vercel environment settings or Vault. Many variables are present in the project environment already; ensure production values are set in your deployment host."
|
|
},
|
|
"export_instructions": {
|
|
"purpose": "This file is a machine-readable site map and operational guide. Use as baseline for exporting docs or generating human-friendly markdown/zip exports.",
|
|
"how_to_export_code": [
|
|
"1. Push latest branch to remote (use Push Code in UI)",
|
|
"2. Build artifacts (npm run build) locally to verify",
|
|
" 3. Package dist/spa and dist/server for deployment",
|
|
" 4. Ensure env vars set on target host",
|
|
" 5. Update DNS to point wildcard domains to host running Express"
|
|
]
|
|
},
|
|
"appendix": {
|
|
"key_files_index": {
|
|
"frontend": ["code/client/App.tsx","code/client/main.tsx","code/client/global.css","code/client/pages/*","code/client/components/*","code/client/contexts/*"],
|
|
"api": ["code/api/* (serverless functions)","code/api/discord/*","code/api/passport/*","code/api/profile/ensure.ts"],
|
|
"server": ["code/server/index.ts","code/server/supabase.ts","code/server/node-build.ts"],
|
|
"discord": ["code/discord-bot/bot.js","code/discord-bot/commands/*"],
|
|
"migrations": ["code/supabase/migrations/*"]
|
|
},
|
|
"contact": "Repository owner / admin (you)"
|
|
}
|
|
}
|