docs: fix DX for new contributors

- Fix port mismatch: Dockerfile EXPOSE 8000, .env.example PORT=8000,
  compose.yml gets explicit PORT=8000
- Add thoughts-frontend/.env.example with all required vars
- Document NEXT_PUBLIC_FEDIVERSE_DOMAIN in README
- Document private cargo registry (k-ap on Gitea)
- Add local dev workflow: make dev-infra → cargo run → bun dev
- Split make targets: test-unit (no DB), test-integration, up

.env.example

@@ -9,7 +9,7 @@ BASE_URL=http://localhost:3000
 
 # Optional
 HOST=0.0.0.0
-PORT=3000
+PORT=8000
 
 # CORS — comma-separated allowed origins, or * for permissive (default: *)
 CORS_ORIGINS=*

Dockerfile

@@ -52,7 +52,7 @@ WORKDIR /app
 COPY --from=builder /build/target/release/thoughts        ./thoughts
 COPY --from=builder /build/target/release/thoughts-worker ./thoughts-worker
 
-EXPOSE 3000
+EXPOSE 8000
 
 ENV RUST_LOG=info
 

Makefile

@@ -16,13 +16,33 @@ fmt-check:
 clippy:
 	cargo clippy -- -D warnings
 
-# Run the test suite.
+# Run the full test suite (requires DATABASE_URL).
 test:
 	cargo test
 
+# Unit tests only — no database required.
+test-unit:
+	cargo test -p domain -p application -p api-types -p activitypub
+
+# Integration tests only — requires DATABASE_URL.
+test-integration:
+	cargo test -p postgres -p postgres-federation -p postgres-search -p presentation
+
 # Apply fmt + clippy auto-fixes in one shot.
 fix:
 	cargo fmt
 	cargo clippy --fix --allow-dirty --allow-staged
 
-.PHONY: check fmt fmt-check clippy test fix
+# Start infra (Postgres + NATS) for local development.
+dev-infra:
+	docker compose up postgres nats -d
+
+# Stop infra.
+dev-infra-down:
+	docker compose down
+
+# Full Docker stack.
+up:
+	docker compose up --build
+
+.PHONY: check fmt fmt-check clippy test test-unit test-integration fix dev-infra dev-infra-down up

README.md

@@ -85,6 +85,11 @@ Users can upload avatar and banner images via `PUT /users/me/avatar` and `PUT /u
 - Rust stable (1.80+)
 - PostgreSQL 15+
 - NATS with JetStream (optional — see [Without NATS](#without-nats))
+- Docker & Docker Compose (for the easiest local setup)
+
+### Private cargo registry
+
+The `k-ap` crate (ActivityPub protocol library) is hosted on a private Gitea registry configured in `.cargo/config.toml`. To build the project you need read access to `git.gabrielkaszewski.dev`. If you're contributing and don't have access, open an issue and I'll sort it out.
 
 ## Environment Variables
 
@@ -121,8 +126,42 @@ Copy `.env.example` to `.env` and fill in your values.
 | `UPLOAD_MAX_BYTES` | `5242880` | Max upload size in bytes (default 5 MiB) |
 | `UPLOAD_ALLOWED_TYPES` | `image/jpeg,image/png,image/gif,image/webp,image/avif` | Comma-separated allowed MIME types |
 
+### Frontend environment
+
+Copy `thoughts-frontend/.env.example` to `thoughts-frontend/.env.local` and adjust:
+
+| Variable | Description |
+|---|---|
+| `NEXT_PUBLIC_API_URL` | API URL for client-side (browser) requests, e.g. `http://localhost:8000` |
+| `NEXT_PUBLIC_SERVER_SIDE_API_URL` | API URL for SSR requests — same as above locally, or `http://api:8000` inside Docker |
+| `NEXT_PUBLIC_FEDIVERSE_DOMAIN` | (Optional) Domain shown on profile fediverse handles, e.g. `yourinstance.example.com` |
+
 ## Run
 
+### Local development (recommended)
+
+Start only the infrastructure containers (Postgres + NATS), then run the Rust backend and Next.js frontend natively for fast iteration:
+
+```bash
+# 1. Start Postgres + NATS
+make dev-infra
+
+# 2. Copy and fill in env files
+cp .env.example .env
+cp thoughts-frontend/.env.example thoughts-frontend/.env.local
+
+# 3. API server (runs migrations automatically on startup)
+cargo run -p bootstrap
+
+# 4. Event worker (separate terminal, optional)
+cargo run -p worker
+
+# 5. Frontend (separate terminal)
+cd thoughts-frontend && bun install && bun dev
+```
+
+### Bare metal
+
 ```bash
 # API server (runs migrations automatically on startup)
 cargo run -p bootstrap
@@ -136,14 +175,20 @@ Both processes share the same PostgreSQL database. The worker is optional but re
 ## Test
 
 ```bash
-# Unit tests — no database required
+# Unit tests only — no database required
-cargo test -p application
+make test-unit
 
-# Full workspace (requires DATABASE_URL pointing to a running PostgreSQL)
+# Integration tests — requires DATABASE_URL pointing to a running PostgreSQL
-cargo test --workspace
+make test-integration
+
+# Everything (unit + integration)
+make test
+
+# Full check suite: fmt + clippy + tests
+make check
 ```
 
-The `application` crate contains unit tests for all event services and use cases backed by in-memory fakes from `domain`'s `test-helpers` feature. These are the fastest feedback loop for business logic.
+`make test-unit` runs domain, application, api-types, and activitypub tests using in-memory fakes — the fastest feedback loop for business logic. `make test-integration` runs the adapter crates against a live PostgreSQL.
 
 ## API
 
@@ -203,12 +248,12 @@ docker build -t thoughts-frontend \
 docker run -p 3000:3000 thoughts-frontend
 ```
 
-### Local development stack
+### Full Docker stack
 
 `compose.yml` spins up the full stack: PostgreSQL, NATS (with JetStream and monitoring on port 8222), the API server, the event worker, and the frontend.
 
 ```bash
-docker compose up
+make up          # or: docker compose up --build
 ```
 
 Services:

compose.yml

@@ -30,6 +30,7 @@ services:
       DATABASE_URL: postgres://postgres:postgres@postgres:5432/thoughts
       JWT_SECRET: change-me-in-production
       BASE_URL: http://localhost:8000
+      PORT: 8000
       NATS_URL: nats://nats:4222
       RUST_LOG: info
       STORAGE_BACKEND: local

crates/adapters/postgres-federation/migrations

@@ -0,0 +1 @@
+../postgres/migrations

crates/adapters/postgres-federation/src/lib.rs

@@ -832,3 +832,91 @@ impl ApUserRepository for PgApUserRepository {
         Ok(n as usize)
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use k_ap::ApUserRepository;
+
+    async fn seed_local_user(pool: &PgPool, username: &str) -> uuid::Uuid {
+        let id = uuid::Uuid::new_v4();
+        sqlx::query(
+            "INSERT INTO users (id,username,email,password_hash,local,created_at,updated_at)
+             VALUES ($1,$2,$3,'h',true,NOW(),NOW())",
+        )
+        .bind(id)
+        .bind(username)
+        .bind(format!("{username}@test.com"))
+        .execute(pool)
+        .await
+        .unwrap();
+        id
+    }
+
+    #[sqlx::test(migrations = "./migrations")]
+    async fn find_by_id_returns_local_user(pool: PgPool) {
+        let id = seed_local_user(&pool, "alice").await;
+        let repo = PgApUserRepository::new(pool, "https://example.com".into());
+
+        let user = repo.find_by_id(id).await.unwrap().unwrap();
+        assert_eq!(user.username, "alice");
+        assert!(user.attachment.is_empty());
+    }
+
+    #[sqlx::test(migrations = "./migrations")]
+    async fn find_by_username_returns_local_user(pool: PgPool) {
+        seed_local_user(&pool, "bob").await;
+        let repo = PgApUserRepository::new(pool, "https://example.com".into());
+
+        let user = repo.find_by_username("bob").await.unwrap().unwrap();
+        assert_eq!(user.username, "bob");
+    }
+
+    #[sqlx::test(migrations = "./migrations")]
+    async fn find_by_id_returns_none_for_missing(pool: PgPool) {
+        let repo = PgApUserRepository::new(pool, "https://example.com".into());
+        let result = repo.find_by_id(uuid::Uuid::new_v4()).await.unwrap();
+        assert!(result.is_none());
+    }
+
+    #[sqlx::test(migrations = "./migrations")]
+    async fn profile_fields_map_to_attachment(pool: PgPool) {
+        let id = seed_local_user(&pool, "carol").await;
+        let fields = serde_json::json!([
+            {"name": "Website", "value": "https://carol.dev"},
+            {"name": "Pronouns", "value": "she/her"}
+        ]);
+        sqlx::query("UPDATE users SET profile_fields = $2 WHERE id = $1")
+            .bind(id)
+            .bind(&fields)
+            .execute(&pool)
+            .await
+            .unwrap();
+
+        let repo = PgApUserRepository::new(pool, "https://example.com".into());
+        let user = repo.find_by_id(id).await.unwrap().unwrap();
+
+        assert_eq!(user.attachment.len(), 2);
+        assert_eq!(user.attachment[0].name, "Website");
+        assert_eq!(user.attachment[0].value, "https://carol.dev");
+        assert_eq!(user.attachment[1].name, "Pronouns");
+        assert_eq!(user.attachment[1].value, "she/her");
+    }
+
+    #[sqlx::test(migrations = "./migrations")]
+    async fn count_users_counts_local_only(pool: PgPool) {
+        seed_local_user(&pool, "local1").await;
+        seed_local_user(&pool, "local2").await;
+        sqlx::query(
+            "INSERT INTO users (id,username,email,password_hash,local,created_at,updated_at)
+             VALUES ($1,'remote','r@r.com','h',false,NOW(),NOW())",
+        )
+        .bind(uuid::Uuid::new_v4())
+        .execute(&pool)
+        .await
+        .unwrap();
+
+        let repo = PgApUserRepository::new(pool, "https://example.com".into());
+        assert_eq!(repo.count_users().await.unwrap(), 2);
+    }
+}

crates/adapters/postgres-search/src/lib.rs

@@ -9,9 +9,9 @@ use domain::{
         user::User,
     },
     ports::SearchPort,
-    value_objects::{Content, Email, PasswordHash, ThoughtId, UserId, Username},
+    value_objects::{Content, ThoughtId, UserId},
 };
-use postgres::user::{UserRow, USER_SELECT};
+use postgres::user::USER_SELECT;
 use sqlx::PgPool;
 
 pub struct PgSearchRepository {
@@ -34,25 +34,15 @@ struct FeedRow {
     sensitive: bool,
     t_local: bool,
     thought_created_at: DateTime<Utc>,
-    updated_at: Option<DateTime<Utc>>,
+    thought_updated_at: Option<DateTime<Utc>>,
-    author_id: uuid::Uuid,
+    note_extensions: Option<serde_json::Value>,
-    username: String,
+    #[sqlx(flatten)]
-    email: String,
+    author: postgres::user::UserRow,
-    password_hash: String,
-    display_name: Option<String>,
-    bio: Option<String>,
-    avatar_url: Option<String>,
-    header_url: Option<String>,
-    custom_css: Option<String>,
-    author_local: bool,
-    author_created_at: DateTime<Utc>,
-    author_updated_at: DateTime<Utc>,
     like_count: i64,
     boost_count: i64,
     reply_count: i64,
     liked_by_viewer: bool,
     boosted_by_viewer: bool,
-    note_extensions: Option<serde_json::Value>,
 }
 
 fn feed_select(viewer: Option<uuid::Uuid>) -> String {
@@ -68,11 +58,11 @@ fn feed_select(viewer: Option<uuid::Uuid>) -> String {
          t.id AS thought_id, t.user_id AS t_user_id, t.content,\n\
          t.in_reply_to_id,\n\
          t.visibility, t.content_warning, t.sensitive, t.local AS t_local,\n\
-         t.created_at AS thought_created_at, t.updated_at, t.note_extensions,\n\
+         t.created_at AS thought_created_at, t.updated_at AS thought_updated_at, t.note_extensions,\n\
-         u.id AS author_id, u.username, u.email, u.password_hash,\n\
+         u.id, u.username, u.email, u.password_hash,\n\
-         u.display_name, u.bio, u.avatar_url, u.header_url, u.custom_css,\n\
+         u.display_name, u.bio, u.avatar_url, u.header_url, u.custom_css, u.profile_fields,\n\
-         u.local AS author_local,\n\
+         u.local,\n\
-         u.created_at AS author_created_at, u.updated_at AS author_updated_at,\n\
+         u.created_at, u.updated_at,\n\
          (SELECT COUNT(*) FROM likes  l WHERE l.thought_id=t.id) AS like_count,\n\
          (SELECT COUNT(*) FROM boosts b WHERE b.thought_id=t.id) AS boost_count,\n\
          (SELECT COUNT(*) FROM thoughts r WHERE r.in_reply_to_id=t.id) AS reply_count,\n\
@@ -92,24 +82,10 @@ fn row_to_entry(r: FeedRow, viewer: Option<uuid::Uuid>) -> Result<FeedEntry, Dom
         sensitive: r.sensitive,
         local: r.t_local,
         created_at: r.thought_created_at,
-        updated_at: r.updated_at,
+        updated_at: r.thought_updated_at,
         note_extensions: r.note_extensions,
     };
-    let author = User {
+    let author = User::from(r.author);
-        id: UserId::from_uuid(r.author_id),
-        username: Username::from_trusted(r.username),
-        email: Email::from_trusted(r.email),
-        password_hash: PasswordHash(r.password_hash),
-        display_name: r.display_name,
-        bio: r.bio,
-        avatar_url: r.avatar_url,
-        header_url: r.header_url,
-        custom_css: r.custom_css,
-        profile_fields: vec![],
-        local: r.author_local,
-        created_at: r.author_created_at,
-        updated_at: r.author_updated_at,
-    };
     Ok(FeedEntry {
         thought,
         author,
@@ -190,7 +166,7 @@ impl SearchPort for PgSearchRepository {
              ORDER BY similarity(username || ' ' || COALESCE(display_name,''), $1) DESC
              LIMIT $2 OFFSET $3"
         );
-        let rows = sqlx::query_as::<_, UserRow>(&sql)
+        let rows = sqlx::query_as::<_, postgres::user::UserRow>(&sql)
             .bind(query)
             .bind(page.limit())
             .bind(page.offset())

crates/adapters/postgres-search/src/tests.rs

@@ -5,6 +5,7 @@ use domain::{
         user::User,
     },
     ports::{SearchPort, ThoughtRepository, UserWriter},
+    value_objects::{Content, Email, PasswordHash, ThoughtId, UserId, Username},
 };
 
 async fn seed_thought(pool: &sqlx::PgPool, username: &str, content: &str) -> (User, Thought) {

crates/adapters/postgres/src/feed/mod.rs

@@ -10,7 +10,7 @@ use domain::{
         user::User,
     },
     ports::{FeedOptions, FeedRepository, FeedRequest, FeedScope, FeedSort},
-    value_objects::{Content, Email, PasswordHash, ThoughtId, UserId, Username},
+    value_objects::{Content, ThoughtId, UserId},
 };
 use sqlx::PgPool;
 
@@ -34,20 +34,10 @@ struct FeedRow {
     sensitive: bool,
     t_local: bool,
     thought_created_at: DateTime<Utc>,
-    updated_at: Option<DateTime<Utc>>,
+    thought_updated_at: Option<DateTime<Utc>>,
     note_extensions: Option<serde_json::Value>,
-    author_id: uuid::Uuid,
+    #[sqlx(flatten)]
-    username: String,
+    author: crate::user::UserRow,
-    email: String,
-    password_hash: String,
-    display_name: Option<String>,
-    bio: Option<String>,
-    avatar_url: Option<String>,
-    header_url: Option<String>,
-    custom_css: Option<String>,
-    author_local: bool,
-    author_created_at: DateTime<Utc>,
-    author_updated_at: DateTime<Utc>,
     like_count: i64,
     boost_count: i64,
     reply_count: i64,
@@ -66,24 +56,10 @@ fn row_to_entry(r: FeedRow, viewer: Option<uuid::Uuid>) -> Result<FeedEntry, Dom
         sensitive: r.sensitive,
         local: r.t_local,
         created_at: r.thought_created_at,
-        updated_at: r.updated_at,
+        updated_at: r.thought_updated_at,
         note_extensions: r.note_extensions,
     };
-    let author = User {
+    let author = User::from(r.author);
-        id: UserId::from_uuid(r.author_id),
-        username: Username::from_trusted(r.username),
-        email: Email::from_trusted(r.email),
-        password_hash: PasswordHash(r.password_hash),
-        display_name: r.display_name,
-        bio: r.bio,
-        avatar_url: r.avatar_url,
-        header_url: r.header_url,
-        custom_css: r.custom_css,
-        profile_fields: vec![],
-        local: r.author_local,
-        created_at: r.author_created_at,
-        updated_at: r.author_updated_at,
-    };
     Ok(FeedEntry {
         thought,
         author,
@@ -135,9 +111,9 @@ impl<'a> FeedSqlBuilder<'a> {
         t.id AS thought_id, t.user_id AS t_user_id, t.content,
         t.in_reply_to_id,
         t.visibility, t.content_warning, t.sensitive, t.local AS t_local,
-        t.created_at AS thought_created_at, t.updated_at,
+        t.created_at AS thought_created_at, t.updated_at AS thought_updated_at,
         t.note_extensions,
-        u.id AS author_id,
+        u.id,
         CASE WHEN NOT u.local AND ra.handle IS NOT NULL AND ra.handle != ''
              THEN '@' || ra.handle ||
                   CASE WHEN ra.handle NOT LIKE '%@%'
@@ -148,9 +124,9 @@ impl<'a> FeedSqlBuilder<'a> {
         COALESCE(ra.display_name, u.display_name) AS display_name,
         u.bio,
         COALESCE(ra.avatar_url, u.avatar_url) AS avatar_url,
-        u.header_url, u.custom_css,
+        u.header_url, u.custom_css, u.profile_fields,
-        u.local AS author_local,
+        u.local,
-        u.created_at AS author_created_at, u.updated_at AS author_updated_at,
+        u.created_at, u.updated_at,
         COALESCE(l_agg.cnt, 0) AS like_count,
         COALESCE(b_agg.cnt, 0) AS boost_count,
         COALESCE(r_agg.cnt, 0) AS reply_count,

crates/adapters/postgres/src/feed/tests.rs

@@ -7,6 +7,7 @@ use domain::{
         user::User,
     },
     ports::{FeedOptions, FeedQuery, FeedRequest, ThoughtRepository, UserWriter},
+    value_objects::{Content, Email, PasswordHash, ThoughtId, UserId, Username},
 };
 
 async fn seed(pool: &sqlx::PgPool, username: &str, content: &str) -> (User, Thought) {

crates/application/src/testing.rs

@@ -5,7 +5,7 @@ use domain::{
     errors::DomainError,
     models::user::User,
     testing::TestStore,
-    value_objects::{Email, PasswordHash, ThoughtId, UserId, Username},
+    value_objects::{Email, ThoughtId, UserId, Username},
 };
 use std::collections::HashMap;
 use std::sync::{Arc, Mutex};
@@ -63,21 +63,11 @@ impl ActivityPubRepository for TestApRepo {
         let handle = url::Url::parse(actor_ap_url)
             .map(|u| u.path().trim_start_matches('/').replace('/', "_"))
             .unwrap_or_else(|_| format!("remote_{}", &uid.to_string()[..8]));
-        let user = User {
+        let user = User::new_remote(
-            id: uid.clone(),
+            uid.clone(),
-            username: Username::from_trusted(handle),
+            Username::from_trusted(handle),
-            email: Email::from_trusted(format!("{}@remote", uid)),
+            Email::from_trusted(format!("{}@remote", uid)),
-            password_hash: PasswordHash("".into()),
+        );
-            display_name: None,
-            bio: None,
-            avatar_url: None,
-            header_url: None,
-            custom_css: None,
-            profile_fields: vec![],
-            local: false,
-            created_at: chrono::Utc::now(),
-            updated_at: chrono::Utc::now(),
-        };
         self.inner.users.lock().unwrap().push(user);
         self.inner
             .actor_ap_ids

crates/domain/src/models/user.rs

@@ -52,4 +52,23 @@ impl User {
             updated_at: now,
         }
     }
+
+    pub fn new_remote(id: UserId, username: Username, email: Email) -> Self {
+        let now = Utc::now();
+        Self {
+            id,
+            username,
+            email,
+            password_hash: PasswordHash(String::new()),
+            display_name: None,
+            bio: None,
+            avatar_url: None,
+            header_url: None,
+            custom_css: None,
+            profile_fields: vec![],
+            local: false,
+            created_at: now,
+            updated_at: now,
+        }
+    }
 }

crates/presentation/src/handlers/auth.rs

@@ -5,6 +5,7 @@ use api_types::{
 };
 use application::use_cases::auth::{login, register, LoginInput, RegisterInput};
 use axum::{http::StatusCode, response::IntoResponse, Json};
+use domain::models::feed::UserSummary;
 use domain::ports::{AuthService, EventPublisher, PasswordHasher, UserRepository};
 
 deps_struct!(AuthDeps {
@@ -37,6 +38,22 @@ pub fn to_user_response(u: &domain::models::user::User) -> UserResponse {
     }
 }
 
+pub fn to_summary_response(u: &UserSummary) -> UserResponse {
+    UserResponse {
+        id: u.id.as_uuid(),
+        username: u.username.clone(),
+        display_name: u.display_name.clone(),
+        bio: u.bio.clone(),
+        avatar_url: u.avatar_url.clone(),
+        header_url: None,
+        custom_css: None,
+        profile_fields: vec![],
+        local: true,
+        is_followed_by_viewer: false,
+        created_at: chrono::Utc::now(),
+    }
+}
+
 #[utoipa::path(
     post, path = "/auth/register",
     request_body = RegisterRequest,

crates/presentation/src/handlers/users/mod.rs

@@ -1,7 +1,7 @@
 use crate::{
     errors::ApiError,
     extractors::{AuthUser, Deps, FromAppState, OptionalAuthUser},
-    handlers::auth::to_user_response,
+    handlers::auth::{to_summary_response, to_user_response},
     state::AppState,
 };
 use api_types::{
@@ -200,23 +200,7 @@ pub async fn get_users(
     }
 
     let result = list_users(&*d.users, page_params).await?;
-    let items: Vec<UserResponse> = result
+    let items: Vec<UserResponse> = result.items.iter().map(to_summary_response).collect();
-        .items
-        .iter()
-        .map(|u| UserResponse {
-            id: u.id.as_uuid(),
-            username: u.username.clone(),
-            display_name: u.display_name.clone(),
-            bio: u.bio.clone(),
-            avatar_url: u.avatar_url.clone(),
-            header_url: None,
-            custom_css: None,
-            profile_fields: vec![],
-            local: true,
-            is_followed_by_viewer: false,
-            created_at: chrono::Utc::now(),
-        })
-        .collect();
     Ok(Json(PagedResponse {
         items,
         total: result.total,

thoughts-frontend/.env.example

@@ -0,0 +1,6 @@
+# API endpoints
+NEXT_PUBLIC_API_URL=http://localhost:8000              # client-side (browser) requests
+NEXT_PUBLIC_SERVER_SIDE_API_URL=http://localhost:8000   # SSR requests (use http://api:8000 inside Docker)
+
+# Fediverse handle display (optional)
+# NEXT_PUBLIC_FEDIVERSE_DOMAIN=yourinstance.example.com

thoughts-frontend/.gitignore

@@ -32,6 +32,7 @@ yarn-error.log*
 
 # env files (can opt-in for committing if needed)
 .env*
+!.env.example
 
 # vercel
 .vercel