🇨🇴 Solana Colombia Website

Welcome to the official repository for the Solana Colombia website. This platform is designed to unite builders, developers, and visionaries across Colombia to build the future of Web3 on Solana.

🚀 Tech Stack

• Framework: Astro 6 (Server-side Rendering)
• Styling: Tailwind CSS 4
• Database: Cloudflare D1 (SQL database for builders/profiles)
• Deployment: Cloudflare Workers via GitHub Actions
• Email: Resend
• Linting/Formatting: Biome via Ultracite preset
• Wallet integration: Direct injected-provider API (window.phantom, window.solflare)

---

🛠️ Getting Started

Prerequisites

• Node.js: v24.0.0 or higher
• Package Manager: pnpm (recommended) or npm

Installation

1. Clone the repository:

   git clone https://github.com/Panmoni/solanacolombia-www.git
   cd solanacolombia-www

2. Install dependencies:

   # Using pnpm (recommended)
   pnpm install
   
   # Or using npm
   npm install

3. Setup environment variables: Copy .env.example to .env and fill in the required values (Resend API key, etc.).

Development

To start the local development server:

# Using pnpm
pnpm dev

# Or using npm
npm run dev

Note: The dev script automatically runs db:pull to sync your local D1 database with the production data before starting the Astro dev server (runs on the real Cloudflare workerd runtime).

Linting & Formatting

# Using pnpm
pnpm lint          # Check for lint errors
pnpm lint:fix      # Fix lint errors
pnpm format        # Check formatting
pnpm format:write  # Fix formatting

# Or using npm
npm run lint
npm run lint:fix
npm run format
npm run format:write

Deployment

# Using pnpm
pnpm deploy

# Or using npm
npm run deploy

AI-assisted development (Claude Code)

This repo ships a set of Claude Code hooks that guard against common footguns when Claude Code is editing files or running commands:

• Protected files: .env, wrangler.toml, schema.sql, and already-applied migrations/*.sql cannot be edited by the AI.
• Blocked commands: wrangler deploy, wrangler d1 execute --remote, wrangler secret put/delete, DROP TABLE, and other irreversible prod operations are refused before execution.
• Auto-format + typecheck: every .astro/.ts edit is run through biome and astro check.
• Pre-PR gate: gh pr create is blocked unless astro check and astro build both pass.

See docs/CLAUDE_HOOKS.md for the full list, the rationale, and how to bypass a hook when legitimately needed.

---

📝 Managing Content

The site uses Astro Content Collections for structured content.

✍️ Adding Blog Posts

Blog posts are stored in src/content/blog/ as Markdown files.

1. Create a new .md file in src/content/blog/.
2. Use the following frontmatter:

   ---
   draft: false
   title: "Your Post Title"
   snippet: "A short summary of the post."
   publishDate: "YYYY-MM-DD HH:mm"
   image:
     src: "/blog/path-to-image.png"
     alt: "Description of image"
   category: "Category Name"
   author: "Author Name"
   tags: ["tag1", "tag2"]
   ---
   # Your Content Here

3. Place images in public/blog/.

👥 Adding Team Members

Team members are stored in src/content/team/ as JSON files.

1. Create a new .json file in src/content/team/ (e.g., name-lastname.json).
2. Add the following structure:

   {
       "name": "Full Name",
       "title": "Role/Title",
       "xUrl": "https://x.com/username",
       "xUsername": "username",
       "image": {
           "src": "/team/filename.png",
           "alt": "Full Name"
       },
       "order": 1
   }

3. Place headshots in public/team/ (recommended size: 400x400px).

📸 Adding Gallery Photos

Gallery items are stored in src/content/gallery/ as JSON files.

1. Create a new .json file in src/content/gallery/ (e.g., 1.json, 2.json).
2. Add the following structure:

   {
       "title": "Event Name",
       "description": "Short description of the event.",
       "image": {
           "src": "/img/filename.jpg",
           "alt": "Event Description"
       },
       "order": 1
   }

3. Place images in public/img/.

👷 Adding Builders & Projects

Unlike the blog or team members, Builders and Projects are dynamic and stored in the Cloudflare D1 database.

• To Add a Builder: Users must connect their Solana wallet on the /builders page and fill out the registration form.
• To Add a Project: Once registered as a builder, users can create and manage their projects directly from their dashboard.
• Local Development: When running locally, the db:pull script syncs the production database so you can see live data.

---

🗄️ Database (Cloudflare D1)

The site uses Cloudflare D1 for dynamic data like the Builders directory.

• Local Development: The database is stored locally in .wrangler/.
• Syncing Data: Use pnpm db:pull (or npm run db:pull) to pull the latest production data to your local environment.
• Wrangler: Use pnpm exec wrangler d1 (or npx wrangler d1) to run migrations or execute SQL queries.

---

📁 Project Structure

/
├── .github/workflows/   # GitHub Actions (auto-deploy to Workers)
├── public/              # Static assets (images, icons, etc.)
├── scripts/security/    # Dependency audit tooling
├── src/
│   ├── components/      # Reusable UI components
│   ├── content/         # Content Collections (Blog, Team, Gallery)
│   ├── layouts/         # Page layouts
│   ├── lib/             # Auth, utilities
│   ├── pages/           # File-based routing
│   │   └── api/         # Server-side API endpoints (D1)
│   ├── styles/          # Global styles (Tailwind CSS)
│   └── content.config.ts # Content schema definitions
├── wrangler.toml        # Cloudflare Workers configuration
└── astro.config.mjs     # Astro configuration

---

🤝 Contributing

We welcome contributions from the community!

1. Fork the repo.
2. Create your feature branch (git checkout -b feature/AmazingFeature).
3. Commit your changes (git commit -m 'Add some AmazingFeature').
4. Push to the branch (git push origin feature/AmazingFeature).
5. Open a Pull Request.

---

🌐 Community

• Telegram: Join our community
• X (Twitter): @SolanaColombia
• Website: solanacolombia.com

---

Built with ❤️ by the Solana Colombia community.