Project Structure

Monorepo Architecture

inkathon uses a monorepo structure powered by Bun workspaces, providing clear separation between different parts of the stack while maintaining easy cross-package imports and shared configurations.

Why Monorepo?

Workspace Structure

Root Directory

• Configuration Files: Shared configs for TypeScript, Biome, Prettier
• Scripts: Global commands that orchestrate across workspaces
• Docker: Production deployment configuration

Frontend Workspace (/frontend)

The Next.js application containing:

• UI Components: Reusable React components
• Web3 Integration: Wallet and contract interaction logic
• Styling: Tailwind CSS configuration
• Type Definitions: Generated from contracts

Contracts Workspace (/contracts)

The ink! smart contracts containing:

• Source Code: Rust contract implementations
• Build Artifacts: Compiled contracts and metadata
• Deployment Scripts: Automated deployment tooling
• Type Generation: PAPI descriptor generation

Documentation Workspace (/docs)

The Fumadocs-powered documentation site:

• Content: MDX documentation files
• Components: Custom documentation components
• Configuration: Fumadocs setup

CLI Workspace (/create-inkathon-app)

The project scaffolding tool:

• Templates: Boilerplate generation
• Scripts: Project initialization logic

Development Workflow

Commands Structure

All commands follow a consistent pattern:

# Run command in specific workspace
bun run -F <workspace> <command>

# Run command in all workspaces
bun run -F '*' <command>

# Examples
bun run -F frontend dev
bun run -F contracts build
bun run -F '*' typecheck

Key Paths

Best Practices

1. Keep workspaces independent: Each workspace should be able to build independently
2. Use workspace protocol: Reference local packages with workspace:*
3. Centralize shared configs: Keep common configurations at the root
4. Document cross-dependencies: Make it clear when packages depend on each other
5. Version together: Use changesets to version all packages together