Hollo - Federated Microblogging Development

Expert guidance for developing Hollo, a federated single-user microblogging software that implements ActivityPub protocol and provides Mastodon-compatible APIs.

Technology Stack

Core Architecture

Directory Structure

```

hollo/

├── bin/ # Entry points (server.ts, routes.ts)

├── src/

│ ├── api/ # Mastodon-compatible REST APIs (v1/, v2/)

│ ├── components/ # Hono JSX components (server-rendered)

│ ├── entities/ # Entity serialization (DB → API)

│ ├── federation/ # ActivityPub via Fedify

│ ├── oauth/ # OAuth 2.0 / OpenID Connect

│ ├── pages/ # Web UI pages

│ ├── import/ # Background data import jobs

│ ├── schema.ts # Drizzle ORM schema

│ └── index.tsx # Main Hono app

├── drizzle/ # SQL migrations

└── tests/ # Test utilities and fixtures

```

Key Dependencies

Development Guidelines

1. JSX Components

**Use Hono's JSX, NOT React:**

```tsx

// ✅ Correct - Hono JSX (no imports needed)

export function MyComponent({ name }: { name: string }) {

return <div>{name}</div>;

}

// ❌ Incorrect - React style

import React from 'react'; // Don't do this

```

2. Database Operations

**Creating migrations:**

```bash

Modify src/schema.ts, then:

pnpm migrate:generate

pnpm migrate # Apply to dev/prod

pnpm migrate:test # Apply to test DB

```

3. Federation with Fedify

4. API Development

5. Security Requirements

6. Testing

**Example test:**

```typescript

import { describe, it, expect, beforeEach } from "vitest";

import { cleanupDatabase, createFixture } from "@/../tests/helpers";

describe("MyFeature", () => {

beforeEach(async () => {

await cleanupDatabase();

});

it("should do something", async () => {

expect(result).toBe(expected);

});

});

```

Essential Commands

Development

```bash

pnpm dev # Start dev server with hot reload

pnpm prod # Start production server

pnpm check # TypeScript + Biome lint

pnpm test # Run tests

pnpm test:ci # Tests without migrations (CI)

pnpm check:coverage # Tests with coverage

```

Utilities

```bash

pnpm list:routes # Display all HTTP routes

pnpm rebuild-timelines # Rebuild home timelines

pnpm migrate:generate # Generate migration from schema

pnpm biome format --write # Format code

pnpm biome check --write # Lint and auto-fix

```

Environment Variables

Required

Storage Configuration

**Filesystem:**

```env

DRIVE_DISK=fs

FS_STORAGE_PATH=/path/to/storage

STORAGE_URL_BASE=https://example.com/assets

```

**S3:**

```env

DRIVE_DISK=s3

AWS_ACCESS_KEY_ID=your-key

AWS_SECRET_ACCESS_KEY=your-secret

S3_REGION=us-east-1

S3_BUCKET=your-bucket

STORAGE_URL_BASE=https://your-bucket.s3.amazonaws.com

```

Optional

Important Constraints

1. **Single-user platform**: Design decisions assume one user per instance

2. **pnpm only**: Package manager enforced via `packageManager` field

3. **No React**: Use Hono's JSX, not React

4. **Zod v4**: Use v4 syntax (different from v3)

5. **AGPL-3.0**: All code must be AGPL-3.0 compatible

6. **Biome formatting**: Follow Biome rules in `biome.json`

7. **Migration safety**: Never edit applied migrations in production

OAuth Support

Performance Considerations

Adding New Environment Variables

When adding new environment variables:

1. Add reading logic in appropriate source file

2. Update environment variable tables in documentation

3. Update installation guides in `docs/src/content/docs/install/*` (all languages)

4. Update Docker Compose files if relevant (`compose.yaml`, `compose-fs.yaml`)

5. Document in `CHANGES.md` under current version