DeepWiki

01.a - System-Architecture

Relevant source files

This document explains the overall architecture of godeep.wiki, including its event-driven design, integration points with external services, and the rationale behind its stateless, log-based correlation model. The system is fundamentally a repository access provisioning platform, not an automated documentation generator—it facilitates payment processing, GitHub repository access granting, and triggers manual documentation workflows.

For detailed component-level descriptions, see Key Components. For data correlation mechanisms, see Data Flow & Correlation. For authentication specifics, see Authentication & GitHub Integration.

godeep.wiki is built on a serverless, event-driven architecture deployed on Vercel. The system orchestrates a multi-stage workflow: payment processing → repository connection → automated repository cloning → manual documentation generation. Unlike typical SaaS applications, this system intentionally lacks a database—all correlation happens through logs and event payloads, optimized for low-volume, owner-operated workflows.

PrincipleImplementationRationale
Event-Drivenntfy.sh message broker coordinates async workflowsDecouples payment, GitHub connection, and automation scripts
StatelessNo database; uses Vercel logs and cookies for correlationSimplifies deployment; suitable for low-volume operation
Dual AuthenticationSeparate OAuth (users) and GitHub App (owner) token systemsSecurity isolation between customer and owner capabilities
Manual WorkflowAutomation ends at repo cloning; documentation generation is manualOwner uses external tools (Devin + Chrome extension) for actual docs
Cookie-Based Statestripe_session_id and github_oauth_state cookies link flowsTemporary state management during OAuth without persistence

Sources: CLAUDE.md L1-L225

README.md L1-L440

High-Level Diagrams

Sources: CLAUDE.md L54-L68

CLAUDE.md L169-L185

README.md L220-L263

High-Level Diagrams

Frontend & RuntimeLink copied!

ComponentTechnologyKey Files
Web FrameworkNext.js 14 (App Router)app/layout.tsx
next.config.mjs
LanguageTypeScript 5.xtsconfig.json
StylingTailwind CSS with oklch colorsapp/globals.css L1-L182
UI ComponentsCustom components + Radix UIcomponents/
directory
HostingVercel (serverless functions)Deployed via Vercel platform

Backend & IntegrationsLink copied!

ServicePurposeEnvironment Variables
StripePayment processing ($10 checkout)STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET
GitHub OAuthUser authentication for dashboardGITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET
GitHub AppOwner repository access (installation tokens)GITHUB_APP_ID, GITHUB_PRIVATE_KEY
ntfy.shEvent message brokerNTFY_TOPIC
Cloudflare AnalyticsTraffic monitoring (optional)NEXT_PUBLIC_CF_BEACON_TOKEN

The automation scripts (ntfy-godeep-automation.sh

ntfy-godeep-automation-remote.sh

) run outside the Next.js application as standalone processes. They subscribe to ntfy.sh notifications and execute repository cloning workflows using git, gh CLI, and the admin token generation API.

Sources: .env.example L1-L15

README.md L206-L218

CLAUDE.md L86-L109

The system's core workflow is orchestrated through asynchronous events rather than synchronous request-response patterns. This design decouples payment verification, GitHub connection confirmation, and repository automation into independent stages.

Sources: CLAUDE.md L32-L42

app/api/auth/github/route.ts

app/api/auth/github/callback/route.ts

app/api/webhooks/stripe/route.ts

High-Level Diagram 2

The system uses ntfy.sh as a lightweight message broker. Two event types trigger notifications:

  1. Payment Completed: app/api/webhooks/stripe/route.ts sends notification when checkout.session.completed webhook fires
  2. GitHub Connected: app/api/auth/github/callback/route.ts sends notification after successful OAuth callback with installation_id

Notification Payload Structure:

Title: "GitHub Repository Connected - [Match ID]"
Message: "[username] connected installation [installation_id]"
Tags: github_connection
Match ID: Last 12 characters of session_id

The automation scripts subscribe to NTFY_TOPIC and parse these notifications to extract installation_id, which they use to call the admin token API.

Sources: CLAUDE.md L153-L167

.env.example L14

High-Level Diagram 4

The system implements two separate authentication mechanisms serving different purposes: OAuth tokens for customers viewing their own repositories, and GitHub App installation tokens for the owner accessing customer repositories.

Sources: CLAUDE.md L68-L80

lib/github-app.ts

app/api/admin/generate-token/route.ts

High-Level Diagram 3

AspectUser OAuth TokenInstallation Access Token
Generated Byapp/api/auth/github/callback/route.ts L80-L95lib/github-app.ts L20-L45
via GitHub App
StorageHTTP-only cookie (github_token)Not stored; generated on-demand
Lifespan24 hours1 hour
ScopeUser's repositories onlyCustomer's selected repositories
Used ByCustomer in app/dashboard/page.tsxOwner in automation scripts + manual access
CredentialsGITHUB_CLIENT_ID + GITHUB_CLIENT_SECRETGITHUB_APP_ID + GITHUB_PRIVATE_KEY
AuthorizationUser-level permissionsInstallation-level permissions (read-only)

Key Security Principle: Users never receive installation tokens, and the owner never uses customer credentials. This architectural separation prevents privilege escalation and enforces principle of least privilege.

Sources: CLAUDE.md L68-L80

CLAUDE.md L110-L125

.env.example L1-L15

Unlike traditional web applications, godeep.wiki intentionally avoids databases. All data correlation happens through:

  1. Cookies: Temporary state during OAuth flow (app/api/auth/github/route.ts L25-L30 sets stripe_session_id and github_oauth_state)
  2. Vercel Logs: Permanent record of session_id + installation_id linkage (app/api/auth/github/callback/route.ts L95-L110 )
  3. Stripe Dashboard: Customer email and payment details searchable by session_id
  4. ntfy Notifications: Carry installation_id in payload for automation scripts

Rationale for No Database:

BenefitExplanation
Deployment SimplicityNo database provisioning, migrations, or backups needed
Cost EfficiencyAvoids database hosting costs for low-volume operation
Operational TransparencyOwner reviews logs manually; no hidden state
Low-Volume OptimizationManual correlation acceptable when processing <10 requests/day
Stateless ScalingVercel functions can scale without database connection limits

Trade-Off: Manual correlation is required. Owner must:

  1. Check Stripe for session_id of payment
  2. Search Vercel logs for matching session_id to find installation_id
  3. Use installation_id in admin panel to generate token

Sources: CLAUDE.md L44-L50

CLAUDE.md L169-L185

High-Level Diagram 5

The application runs entirely on Vercel's serverless platform:

  • Web Pages: Rendered as serverless functions (app router pages)
  • API Routes: app/api/**/route.ts deployed as individual endpoints
  • Server Actions: app/actions.ts bundled with pages that invoke them
  • Edge Functions: None (uses standard Node.js runtime)
  • Static Assets: public/ served via Vercel CDN

Configuration: next.config.mjs L1-L10

disables optimizations for static export compatibility.

Sources: next.config.mjs

README.md L265-L290

The automation pipeline (ntfy-godeep-automation.sh

ntfy-godeep-automation-remote.sh

) runs outside Vercel as long-running processes. These scripts:

  1. Subscribe to NTFY_TOPIC using curl in blocking mode
  2. Parse JSON notifications to extract installation_id
  3. Call api/admin/generate-token to obtain temporary access token
  4. Clone customer repository using git clone
  5. Re-initialize as new repository and push to klaudioz/customer-email-reponame

Why External Scripts?

  • Vercel functions have 10-second timeout (hobby plan) or 5-minute max (pro)
  • Repository cloning for large repos may exceed these limits
  • Long-running ntfy subscription requires persistent connection
  • Owner's local machine or VPS provides unlimited execution time

Sources: ntfy-godeep-automation.sh

ntfy-godeep-automation-remote.sh

High-Level Diagram 4

LayerImplementationCode Reference
TLS EncryptionAll traffic over HTTPS (enforced by Vercel)Production environment
CSRF ProtectionOAuth state parameter via crypto.randomUUID()app/api/auth/github/route.ts L20-L25
XSS MitigationHTTP-only cookies for token storageapp/api/auth/github/callback/route.ts L105-L110
Webhook VerificationStripe signature validationapp/api/webhooks/stripe/route.ts L15-L30
Webhook VerificationGitHub signature validationapp/api/webhooks/github/route.ts L15-L30

All sensitive credentials stored in environment variables (see .env.example

):

  • Server-Side Only: GITHUB_PRIVATE_KEY, STRIPE_SECRET_KEY, GITHUB_CLIENT_SECRET
  • Client-Exposed: NEXT_PUBLIC_ADMIN_PASSWORD (unusual pattern, see below)

Security Consideration: The admin password (.env.example L8

) uses NEXT_PUBLIC_ prefix, making it accessible in browser bundle. This suggests simplified security model suitable for single-owner operation rather than enterprise-grade access control. For production hardening, consider:

  • Moving admin auth to server-side session
  • Implementing rate limiting on api/admin/generate-token
  • Adding IP allowlisting for admin routes

Sources: .env.example L1-L15

CLAUDE.md L86-L109

High-Level Diagram 6

GitHub App Permissions (github-app-description.md L19-L21

):

  • contents: read - Read repository files
  • metadata: read - Read repository metadata
  • email_addresses: read - Read user email (for customer communication)

Critical User Choice: During GitHub App installation, users choose between:

  • "All repositories" - Grants access to every repo in account
  • "Only select repositories" - Grants access only to chosen repos

The app description (github-app-description.md L8-L10

) strongly recommends selecting specific repositories to minimize security exposure.

Sources: github-app-description.md L1-L46

README.md L128-L144

CLAUDE.md L206-L210

godeep.wiki's architecture prioritizes simplicity and manual control over automation and scale. The event-driven design using ntfy.sh enables asynchronous processing without complex job queues, while the stateless, log-based correlation eliminates database dependencies. The dual authentication model (OAuth for customers, GitHub App for owner) provides security isolation, and the external automation scripts work around serverless execution time limits. This architecture is optimized for low-volume (1-10 customers/day), owner-operated workflows where manual intervention is acceptable and even preferred for quality control.

Sources: CLAUDE.md L1-L225

README.md L1-L440

All High-Level Diagrams

Refresh this wiki

Last indexed: 23 November 2025 (922b35)

On this page

Ask Devin about godeep.wiki-jb

01.a - System-Architecture | DeepWiki | godeep.wiki