# amir-baddour/airdropx architecture

> Architecture diagram of the GitHub repository amir-baddour/airdropx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amir-baddour/airdropx
- Repository: https://github.com/amir-baddour/airdropx

## Overview

AirDropX is a multi-tenant airdrop campaign platform with a React frontend for companies, administrators, and claimants; payouts are mocked. The frontend workflow routes users through authentication and company campaign management, while public pages support claims and status checks. Campaign setup includes task management, and admin screens expose oversight and moderation. The README documents Google OAuth, public campaign publishing, manual proof review, and payout lifecycle capabilities, but backend implementation is outside this tree. Edges reflect shown routing/imports and documented API or product relationships; unsampled feature-to-query calls are not inferred.

Main entry points: [`frontend/src/App.tsx`](https://github.com/amir-baddour/airdropx/blob/main/frontend/src/App.tsx) (Application router), [`frontend/src/lib/queries.ts`](https://github.com/amir-baddour/airdropx/blob/main/frontend/src/lib/queries.ts) (Query layer), [`frontend/src/features/admin/AdminPage.tsx`](https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/admin/AdminPage.tsx) (Admin console), [`frontend/src/features/auth/AuthCallbackPage.tsx`](https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/auth/AuthCallbackPage.tsx) (OAuth callback)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_routing["App routing"]
  node_app["Application router<br/>[App.tsx]"]
  node_landing["Landing and docs"]
end

subgraph group_identity["Identity"]
  node_login["Google sign-in<br/>[LoginPage.tsx]"]
  node_callback["OAuth callback"]
  node_auth_flow["OAuth initiation<br/>[auth.ts]"]
  node_session[("Session storage<br/>[session.ts]")]
  node_guard["Protected routes<br/>[RequireAuth.tsx]"]
end

subgraph group_company["Company campaigns"]
  node_dashboard["Campaign dashboard<br/>[AirdropsPage.tsx]"]
  node_create_campaign["Create campaign"]
  node_campaign_detail["Campaign workspace<br/>[AirdropPage.tsx]"]
  node_task_management["Task management<br/>[TasksTab.tsx]"]
  node_recipient_management["Recipient management<br/>[RecipientsTab.tsx]"]
  node_claim_review["Claim review<br/>[ClaimsTab.tsx]"]
  node_lifecycle["Campaign lifecycle"]
end

subgraph group_claim["Claimant experience"]
  node_public_claim["Public claim flow<br/>[ClaimPage.tsx]"]
  node_public_shell["Public page shell<br/>[PublicShell.tsx]"]
  node_status["Claim status<br/>[StatusPage.tsx]"]
end

subgraph group_oversight["Administration"]
  node_admin["Admin console<br/>[AdminPage.tsx]"]
  node_admin_overview["Platform overview<br/>[AdminOverview.tsx]"]
  node_admin_companies["Company moderation<br/>[AdminCompanies.tsx]"]
  node_admin_audit["Audit history<br/>[AdminAudit.tsx]"]
end

node_company_user(("Company user"))
node_claimant(("Claimant"))
node_admin_user(("Administrator"))
node_query_layer["Query layer<br/>[queries.ts]"]
node_api_client["API client<br/>[api.ts]"]
node_backend["Spark API"]
node_spaces[("DigitalOcean Spaces")]

node_company_user -->|"opens"| node_app
node_claimant -->|"opens"| node_app
node_admin_user -->|"opens"| node_app
node_app -->|"routes"| node_landing
node_app -->|"routes"| node_login
node_app -->|"routes"| node_callback
node_app -->|"routes"| node_public_claim
node_app -->|"routes"| node_status
node_app -->|"protects"| node_guard
node_app -->|"routes"| node_dashboard
node_app -->|"routes"| node_campaign_detail
node_app -->|"routes"| node_admin
node_login -->|"starts sign-in"| node_auth_flow
node_auth_flow -->|"redirects"| node_callback
node_callback -->|"saves session"| node_session
node_guard -->|"checks session"| node_session
node_dashboard -->|"opens"| node_create_campaign
node_create_campaign -->|"creates via"| node_query_layer
node_campaign_detail -.->|"shows tab"| node_task_management
node_public_claim -->|"renders within"| node_public_shell
node_status -->|"renders within"| node_public_shell
node_admin -->|"renders"| node_admin_overview
node_admin -->|"renders"| node_admin_companies
node_admin -->|"renders"| node_admin_audit
node_admin_overview -->|"loads metrics"| node_query_layer
node_admin_companies -->|"loads companies"| node_query_layer
node_task_management -->|"loads tasks"| node_query_layer
node_query_layer -->|"calls"| node_api_client
node_api_client -->|"sends requests"| node_backend
node_backend -->|"publishes pages"| node_spaces

click node_app "https://github.com/amir-baddour/airdropx/blob/main/frontend/src/App.tsx"
click node_landing "https://github.com/amir-baddour/airdropx/tree/main/frontend/src/features/landing"
click node_login "https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/auth/LoginPage.tsx"
click node_callback "https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/auth/AuthCallbackPage.tsx"
click node_auth_flow "https://github.com/amir-baddour/airdropx/blob/main/frontend/src/lib/auth.ts"
click node_session "https://github.com/amir-baddour/airdropx/blob/main/frontend/src/lib/session.ts"
click node_guard "https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/auth/RequireAuth.tsx"
click node_dashboard "https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/dashboard/AirdropsPage.tsx"
click node_create_campaign "https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/dashboard/CreateAirdropDialog.tsx"
click node_campaign_detail "https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/airdrop/AirdropPage.tsx"
click node_task_management "https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/airdrop/TasksTab.tsx"
click node_recipient_management "https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/airdrop/RecipientsTab.tsx"
click node_claim_review "https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/airdrop/ClaimsTab.tsx"
click node_lifecycle "https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/airdrop/LifecycleStepper.tsx"
click node_public_claim "https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/public/ClaimPage.tsx"
click node_public_shell "https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/public/PublicShell.tsx"
click node_status "https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/public/StatusPage.tsx"
click node_admin "https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/admin/AdminPage.tsx"
click node_admin_overview "https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/admin/AdminOverview.tsx"
click node_admin_companies "https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/admin/AdminCompanies.tsx"
click node_admin_audit "https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/admin/AdminAudit.tsx"
click node_query_layer "https://github.com/amir-baddour/airdropx/blob/main/frontend/src/lib/queries.ts"
click node_api_client "https://github.com/amir-baddour/airdropx/blob/main/frontend/src/lib/api.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_landing,node_company_user,node_api_client toneBlue
class node_login,node_callback,node_auth_flow,node_session,node_guard,node_spaces toneAmber
class node_dashboard,node_create_campaign,node_campaign_detail,node_task_management,node_recipient_management,node_claim_review,node_lifecycle,node_backend toneMint
class node_public_claim,node_public_shell,node_status toneRose
class node_admin,node_admin_overview,node_admin_companies,node_admin_audit,node_claimant,node_admin_user toneIndigo
class node_query_layer toneTeal
```

## Components

### App routing

- [Application router](https://github.com/amir-baddour/airdropx/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Landing and docs](https://github.com/amir-baddour/airdropx/tree/main/frontend/src/features/landing): `frontend/src/features/landing`

### Identity

- [Google sign-in](https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/auth/LoginPage.tsx): `frontend/src/features/auth/LoginPage.tsx`
- [OAuth callback](https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/auth/AuthCallbackPage.tsx): `frontend/src/features/auth/AuthCallbackPage.tsx`
- [OAuth initiation](https://github.com/amir-baddour/airdropx/blob/main/frontend/src/lib/auth.ts): `frontend/src/lib/auth.ts`
- [Session storage](https://github.com/amir-baddour/airdropx/blob/main/frontend/src/lib/session.ts): `frontend/src/lib/session.ts`
- [Protected routes](https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/auth/RequireAuth.tsx): `frontend/src/features/auth/RequireAuth.tsx`

### Company campaigns

- [Campaign dashboard](https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/dashboard/AirdropsPage.tsx): `frontend/src/features/dashboard/AirdropsPage.tsx`
- [Create campaign](https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/dashboard/CreateAirdropDialog.tsx): `frontend/src/features/dashboard/CreateAirdropDialog.tsx`
- [Campaign workspace](https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/airdrop/AirdropPage.tsx): `frontend/src/features/airdrop/AirdropPage.tsx`
- [Task management](https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/airdrop/TasksTab.tsx): `frontend/src/features/airdrop/TasksTab.tsx`
- [Recipient management](https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/airdrop/RecipientsTab.tsx): `frontend/src/features/airdrop/RecipientsTab.tsx`
- [Claim review](https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/airdrop/ClaimsTab.tsx): `frontend/src/features/airdrop/ClaimsTab.tsx`
- [Campaign lifecycle](https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/airdrop/LifecycleStepper.tsx): `frontend/src/features/airdrop/LifecycleStepper.tsx`

### Claimant experience

- [Public claim flow](https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/public/ClaimPage.tsx): `frontend/src/features/public/ClaimPage.tsx`
- [Public page shell](https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/public/PublicShell.tsx): `frontend/src/features/public/PublicShell.tsx`
- [Claim status](https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/public/StatusPage.tsx): `frontend/src/features/public/StatusPage.tsx`

### Administration

- [Admin console](https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/admin/AdminPage.tsx): `frontend/src/features/admin/AdminPage.tsx`
- [Platform overview](https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/admin/AdminOverview.tsx): `frontend/src/features/admin/AdminOverview.tsx`
- [Company moderation](https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/admin/AdminCompanies.tsx): `frontend/src/features/admin/AdminCompanies.tsx`
- [Audit history](https://github.com/amir-baddour/airdropx/blob/main/frontend/src/features/admin/AdminAudit.tsx): `frontend/src/features/admin/AdminAudit.tsx`

### Other components

- **Company user**
- **Claimant**
- **Administrator**
- [Query layer](https://github.com/amir-baddour/airdropx/blob/main/frontend/src/lib/queries.ts): `frontend/src/lib/queries.ts`
- [API client](https://github.com/amir-baddour/airdropx/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- **Spark API**
- **DigitalOcean Spaces**

## Connections

- Company user → Application router: opens
- Claimant → Application router: opens
- Administrator → Application router: opens
- Application router → Landing and docs: routes (evidence: `frontend/src/App.tsx`)
- Application router → Google sign-in: routes (evidence: `frontend/src/App.tsx`)
- Application router → OAuth callback: routes (evidence: `frontend/src/App.tsx`)
- Application router → Public claim flow: routes (evidence: `frontend/src/App.tsx`)
- Application router → Claim status: routes (evidence: `frontend/src/App.tsx`)
- Application router → Protected routes: protects (evidence: `frontend/src/App.tsx`)
- Application router → Campaign dashboard: routes (evidence: `frontend/src/App.tsx`)
- Application router → Campaign workspace: routes (evidence: `frontend/src/App.tsx`)
- Application router → Admin console: routes (evidence: `frontend/src/App.tsx`)
- Google sign-in → OAuth initiation: starts sign-in (evidence: `frontend/src/features/auth/LoginPage.tsx`)
- OAuth initiation → OAuth callback: redirects (evidence: `frontend/src/lib/auth.ts`)
- OAuth callback → Session storage: saves session (evidence: `frontend/src/features/auth/AuthCallbackPage.tsx`)
- Protected routes → Session storage: checks session (evidence: `frontend/src/features/auth/RequireAuth.tsx`)
- Campaign dashboard → Create campaign: opens (evidence: `frontend/src/features/dashboard/AirdropsPage.tsx`)
- Create campaign → Query layer: creates via (evidence: `frontend/src/features/dashboard/CreateAirdropDialog.tsx`)
- Campaign workspace → Task management: shows tab
- Public claim flow → Public page shell: renders within (evidence: `frontend/src/features/public/ClaimPage.tsx`)
- Claim status → Public page shell: renders within (evidence: `frontend/src/features/public/StatusPage.tsx`)
- Admin console → Platform overview: renders (evidence: `frontend/src/features/admin/AdminPage.tsx`)
- Admin console → Company moderation: renders (evidence: `frontend/src/features/admin/AdminPage.tsx`)
- Admin console → Audit history: renders (evidence: `frontend/src/features/admin/AdminPage.tsx`)
- Platform overview → Query layer: loads metrics (evidence: `frontend/src/features/admin/AdminOverview.tsx`)
- Company moderation → Query layer: loads companies (evidence: `frontend/src/features/admin/AdminCompanies.tsx`)
- Task management → Query layer: loads tasks (evidence: `frontend/src/features/airdrop/TasksTab.tsx`)
- Query layer → API client: calls (evidence: `frontend/src/lib/queries.ts`)
- API client → Spark API: sends requests
- Spark API → DigitalOcean Spaces: publishes pages
