Codebase Structure

How the ZapTracker codebase is organized.

Overview

The project follows a feature-based organization where related files are grouped by domain rather than file type.

src/
├── components/          # Vue components by feature
├── composables/         # Composition functions by domain
├── pages/               # Page/route components
├── utils/               # Utility functions by domain
├── services/            # Business logic services
├── assets/              # Static assets
├── App.vue              # Root component
├── main.js              # Entry point
└── style.css            # Global styles

Components

Vue components organized by feature area:

src/components/
├── analytics/       # Analytics and metrics
├── audience/        # Audience management
├── badges/          # Badge display
├── campaigns/       # Campaign/fundraising
├── content/         # Content creation
├── layout/          # Sidebar, TopBar
├── modals/          # Modal dialogs
├── profile/         # Profile display/edit
├── settings/        # Configuration
├── shared/          # Reusable components
├── wallet/          # Wallet/NWC
└── zaps/            # Zap feed, Lightning

Analytics Components

Component	Purpose
Analytics.vue	Main analytics dashboard
EngagementAnalytics.vue	Engagement metrics display
EngagementMetrics.vue	Detailed metrics
StatsCards.vue	Stats card grid

Content Components

Component	Purpose
BlogEditor.vue	Long-form article editor
ContentForm.vue	Content creation form
ContentList.vue	List of content items
ContentPerformance.vue	Content analytics
MentionInput.vue	User mention input

Layout Components

Component	Purpose
Sidebar.vue	Main navigation
TopBar.vue	Top navigation bar

Composables

Vue Composition API functions by domain:

src/composables/
├── analytics/       # Engagement metrics
├── audience/        # Audience & follow lists
├── auth/            # Nostr authentication
├── campaigns/       # Campaign management
├── content/         # Content operations
├── core/            # BTC price, notifications
├── social/          # Badges, chat
└── wallet/          # Lightning Network

Key Composables

Composable	Purpose
useNostrAuth	Authentication state
useLightningNetwork	Wallet operations
useContent	Content management
useAudience	Audience data
useCampaigns	Campaign logic
useEngagementMetrics	Analytics data

Utilities

Pure functions organized by domain:

src/utils/
├── account/         # Account management
├── chart/           # Chart utilities
├── content/         # Content processing
├── core/            # Date, time, data utils
├── network/         # Relay management
├── profile/         # Avatar, profile fetch
└── wallet/          # Invoice, NWC, payments

Core Utilities

File	Purpose
dateUtils.js	Date formatting
dataMapper.js	Data transformation
timeFilter.js	Time-based filtering

Wallet Utilities

File	Purpose
invoiceUtils.js	Lightning invoice handling
nwcClient.js	NWC client implementation
nwcPayment.js	Payment processing

Pages

Top-level route components:

src/pages/
├── Dashboard.vue
├── Analytics.vue
├── ZapFeed.vue
├── Wallet.vue
├── Content.vue
├── Campaigns.vue
├── CampaignView.vue
├── Audience.vue
├── Calendar.vue
├── Notes.vue
├── Settings.vue
└── ...

Import Patterns

Component to Composable

// From src/components/wallet/WalletBalance.vue
import { useLightningNetwork } from '../../composables/wallet/useLightningNetwork.js'

Component to Utility

// From src/components/analytics/Analytics.vue
import { formatDate } from '../../utils/core/dateUtils.js'

Composable to Utility

// From src/composables/wallet/useLightningNetwork.js
import { parseInvoice } from '../../utils/wallet/invoiceUtils.js'

Adding New Features

1. Determine Feature Domain

Does it fit an existing category or need a new one?

2. Create Components

src/components/{feature}/
├── FeatureMain.vue
├── FeatureItem.vue
└── FeatureModal.vue

3. Create Composables

src/composables/{feature}/
└── useFeature.js

4. Create Utilities

src/utils/{feature}/
└── featureUtils.js

5. Add to Router (if page)

Update routing configuration for new pages.

Best Practices

Colocation

Keep related files together:

• Components with their composables
• Utils near their consumers

Single Responsibility

Each file should do one thing:

• Components handle UI
• Composables handle state/logic
• Utils handle pure functions

Avoid Circular Dependencies

Structure imports to flow in one direction:

Pages → Components → Composables → Utils

Naming Conventions

Type	Convention	Example
Component	PascalCase	WalletBalance.vue
Composable	use prefix	useWallet.js
Utility	camelCase	formatSats.js

Related

• Components Reference
• Composables Reference
• Contributing Guidelines