Hollo Federated Microblogging Development

Develop and maintain Hollo, a federated single-user microblogging software powered by Fedify that implements the ActivityPub protocol for federation with platforms like Mastodon and Misskey, with Mastodon-compatible APIs for client integration.

Technology Stack

Project Structure

```

hollo/

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

├── src/

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

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

│ ├── entities/ # DB → API response serialization

│ ├── federation/ # ActivityPub via Fedify (inbox, actors, objects)

│ ├── import/ # Background data import (processors, worker)

│ ├── oauth/ # OAuth 2.0/OIDC (middleware, endpoints)

│ ├── pages/ # Web UI pages (Hono JSX)

│ ├── public/ # Static assets

│ ├── index.tsx # Main Hono app composition

│ ├── schema.ts # Drizzle ORM database schema (~1300 lines)

│ └── db.ts # Database connection

├── scripts/ # Utility scripts (rebuild-timelines.ts)

├── tests/ # Test utilities and fixtures

├── drizzle/ # Database migrations (SQL files)

└── docs/ # Documentation site (Astro/Starlight)

```

Development Instructions

1. Code Style and Architecture

**JSX Usage (Hono, NOT React)**

```typescript

// Correct - Hono JSX

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

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

}

// Incorrect - React style (don't do this)

import React from 'react';

```

**TypeScript Standards**

2. Database Development

**Schema Changes**

1. Modify `src/schema.ts`

2. Generate migration: `pnpm migrate:generate`

3. Apply migration: `pnpm migrate` (or `pnpm migrate:test` for test DB)

**Guidelines**

3. API Development (Mastodon Compatible)

**Standards**

**OAuth Implementation**

4. Federation Guidelines

**ActivityPub Implementation**

**Key Files**

5. Security Requirements

**Input Validation**

**Authentication**

6. Testing

**Test Structure**

```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);

});

});

```

**Configuration**

7. Performance Optimization

8. Development Commands

```bash

Development

pnpm dev # Start dev server with hot reload

pnpm prod # Start production server

pnpm check # TypeScript check + Biome lint

pnpm test # Run tests

pnpm test:ci # Run tests without migrations (CI)

pnpm check:coverage # Tests with coverage

Utilities

pnpm list:routes # Display all HTTP routes

pnpm rebuild-timelines # Rebuild home timelines

pnpm migrate # Apply pending migrations

pnpm migrate:test # Apply migrations to test DB

pnpm migrate:generate # Generate migration from schema

Formatting

pnpm biome format --write . # Format code

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

```

9. Environment Variables

**Required**

**Storage (Filesystem)**

```env

DRIVE_DISK=fs

FS_STORAGE_PATH=/path/to/storage

STORAGE_URL_BASE=https://example.com/assets

```

**Storage (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://bucket.s3.amazonaws.com

```

**Optional**

10. Adding New Environment Variables

When adding environment variables, update:

1. Source code (appropriate file: logging.ts, storage.ts, etc.)

2. AGENTS.md (this guidelines file)

3. Documentation in `docs/src/content/docs/install/*` (all languages: English, Japanese, Korean, Simplified Chinese)

4. Docker Compose files (compose.yaml, compose-fs.yaml)

5. CHANGES.md changelog

Key Architectural Patterns

Entity Serialization

Transform database records to Mastodon API responses via `src/entities/` (e.g., `entities/status.ts`)

Import System

Long-running background jobs use import worker (`src/import/worker.ts`, `src/import/processors.ts`)

Component Organization

Server-rendered Hono JSX components in `src/components/` for UI, `src/pages/` for full pages

Federation Layer

ActivityPub implementation isolated in `src/federation/` with clear separation: index (setup), actor (dispatchers), inbox (handlers), objects (dispatchers)

Important Constraints