Welcome to Truth Social.

This internship is built around genuine participation — not shadowing, not busy work. You'll be in real meetings, shipping real code, and learning the tools that define how modern software gets built. The goal is for you to leave with hands-on experience across the full development lifecycle and a concrete understanding of where the industry is headed.

Before working through the modules below, get the project running on your machine. Do this first — many of the modules ask you to open files and poke around in the running app.

1. Clone the repository

The project lives on GitLab. Make sure your SSH key is added to your GitLab account, then clone it (ask your team lead for the exact repo URL if you don't have it):

# clone truth-web from GitLab
git clone git@gitlab.com:<org>/truth-web.git
cd truth-web

2. Install dependencies

The project uses npm. From the repo root:

npm install

3. Configure your environment variables

Copy the example env file and fill in the values. At minimum you'll need VITE_BACKEND_URL pointing at the API:

cp .env.example .env

4. Start the dev server

npm run dev

This starts Vite and serves the app at localhost:3000 with hot module reloading — edits show up in the browser without a manual refresh.

The app is a React 18 single-page application. The entire UI runs in the browser — there are no server-rendered pages and no page reloads between views. The Truth Social API is a separate back-end server; this repo is the front end only.

Key constraints

TypeScript adds a static type system on top of JavaScript. The compiler catches type errors before the code runs, and editors use the types for autocomplete and inline documentation. Strict null checks are enabled — null and undefined are separate and must be handled explicitly.

Syntax primer

// Types describe the shape of data
type Status = "public" | "self" | "group";   // union — one of these values

// Interfaces describe object shapes (used for component props)
interface ButtonProps {
  label: string;
  onClick: () => void;
  disabled?: boolean;     // ? = optional
}

// Generics work like templates
function first<T>(arr: T[]): T | undefined {
  return arr[0];
}

// async/await — returns Promise<T>
async function fetchUser(id: string): Promise<User> {
  const res = await fetch(`/api/v1/accounts/${id}`);
  return res.json();
}

Project type conventions

// Use `type` for unions, intersections, and computed shapes
type ReadonlyAccount = Readonly<Account>;

// Use `interface` for prop bags
interface ChatItemProps {
  isRead: boolean;        // booleans: always is* / has* / can* prefix
  hasAttachments: boolean;
  canDelete: boolean;
}

// Derive types from Zod schemas — never write both by hand
import z from "zod";
const schema = z.object({ id: z.string(), name: z.string() });
type Account = z.infer<typeof schema>;   // type comes from the schema

A React component is a function that takes props and returns UI (JSX). React calls it again whenever its props or state change. The framework diffs the result against the previous render and only updates what changed in the DOM.

Component anatomy

interface UserBadgeProps {
  username: string;
  isVerified: boolean;
}

const UserBadge = ({ username, isVerified }: UserBadgeProps) => (
  <span>
    @{username}
    {isVerified && <VerificationBadge />}
  </span>
);

Hooks you'll use most

src/
├── api/              # Data layer: hooks, schemas, React Query integration
│   ├── core/         # useEntity, useEntities, useEntityMutation
│   └── <feature>/   # Feature-specific hooks (e.g. api/chats/, api/groups/)
├── components/       # Shared UI components reusable across features
│   └── ui/           # Primitive UI kit: Button, Modal, Select, Input…
├── contexts/         # React contexts (global shared state)
├── features/         # Full page / screen implementations
│   └── ui/           # App shell, routing, layout
├── hooks/            # Shared custom hooks
├── schemas/          # Zod schemas — single source of truth for API shapes
├── types/            # Global TypeScript types (non-schema)
├── utils/            # Pure utility functions
└── styles/           # Tailwind config and global CSS

The three-layer rule

Every feature follows the same structure. A component should never call fetch or axios directly — always go through the hook layer.

The Truth Social API is a Mastodon-compatible REST API. Every feature in this repo is ultimately a wrapper around HTTP calls to that API. Understanding how those calls are made, authenticated, paginated, and validated is fundamental to working in this codebase.

Authentication

The app supports two auth states: logged in (bearer token) and logged out (visitor token). The correct headers are applied automatically by the HTTP client — you never attach them manually.

The HTTP client

The client is built on axios, configured in src/api/index.ts. It sets the baseURL to VITE_BACKEND_URL and attaches the auth header. In development, /api/*, /oauth/*, /pleroma/*, and /socket paths are proxied to the backend via Vite — no CORS issues locally.

// The correct way to make an authenticated request
const api = useApi();                         // axios instance with auth header

// GET
const response = await api.get("/api/v1/accounts/verify_credentials");

// POST with body
const response = await api.post("/api/v1/statuses", {
  status: "Hello, Truth!",
  visibility: "public",
});

// DELETE
const response = await api.delete(`/api/v1/statuses/${id}`);

Pagination via Link headers

List endpoints are paginated using cursor-based pagination — never offset-based. The API returns a Link HTTP response header containing URLs for the next and previous pages. The client parses these with the http-link-header library.

// Response headers from a timeline request:
// Link: <https://truthsocial.com/api/v1/timelines/home?max_id=123>; rel="next",
//       <https://truthsocial.com/api/v1/timelines/home?since_id=456>; rel="prev"

import { getNextLink, getPrevLink } from "@/api";

const nextUrl = getNextLink(response);   // pass to next page fetch
const prevUrl = getPrevLink(response);   // pass to prev page fetch

Some endpoints use an X-Total-Count response header to communicate total result counts without sending all the data. useEntities exposes a getTotalCount callback for this.

Request → Response lifecycle

Here is what happens end-to-end when a component triggers a data fetch:

Error handling

The API returns errors as JSON. Two error shapes exist — standard API errors and Pepe (internal service) errors — both defined in src/types/api.ts.

// Standard API error shape
interface ApiError {
  error: string;
  error_message: string;
  error_code: string;
  message: string;
  errors: {
    error_code: string;
    error_field: string | null;
    error_message: string;
  }[];
}

The mutation layer in useEntityMutation handles two status codes automatically — you don't need to handle these yourself:

The Zod boundary

Zod sits at the exact point where raw API data enters the app. Nothing upstream of useEntity / useEntities ever touches unvalidated data. This means:

• If the API adds a new field, it's silently ignored until you add it to the schema.
• If the API removes or renames a field, the .catch() default fires and the app keeps working.
• If the API returns an entirely wrong shape, the schema fails safe and the component receives the defaulted values rather than crashing.

Relationships as a second request

Account and group list endpoints don't embed relationship data (follow state, membership role, etc.) in the response — that comes from a separate /api/v1/accounts/relationships or /api/v1/groups/relationships call. useEntities handles this automatically when you pass a relationshipConfig option — it batches the IDs from the current page, fetches relationships, and merges them into the result.

React Query manages all async server data. It caches responses, deduplicates in-flight requests, and re-fetches when data goes stale — you don't manage loading/error state by hand.

Reading data

import { useEntity, QueryKeys } from "@/api/core";
import { accountSchema } from "@/schemas/account";

const { entity: account, isLoading } = useEntity({
  id,
  queryKey: QueryKeys.accounts.account(id),
  endpoint: `/api/v1/accounts/${id}`,
  schema: accountSchema,   // response is validated + typed automatically
});

Mutating data

const { mutate: followUser } = useEntityMutation({
  queryKey: QueryKeys.accounts.account(id),
  endpoint: `/api/v1/accounts/${id}/follow`,
  method: "POST",
  onMutate: async () => { /* snapshot cache for optimistic update */ },
  onError: (_, __, context) => { /* roll back from snapshot */ },
});

Optimistic updates

When a user takes an action (follow, like, etc.), the UI should feel instant:

The API can return unexpected shapes — missing fields, wrong types, extra nulls. Zod validates the response at the boundary so the app never crashes on malformed data, and gives us a strongly-typed object to work with.

import z from "zod";

const statusSchema = z.object({
  id:          z.string(),
  content:     z.string().catch(""),                              // safe default on failure
  favourited:  z.boolean().catch(false),
  visibility:  z.enum(["public", "self", "group"]).catch("public"),
  created_at:  z.string().datetime().optional(),
});

type Status = z.infer<typeof statusSchema>;   // type derived from schema

Tailwind is a utility-first CSS framework. Instead of writing a CSS class with properties, you apply small, single-purpose utility classes directly on the element.

import { cn } from "@/utils/cn";

<div className={cn(
  "rounded-lg border border-border px-4 py-2",
  isActive   && "bg-primary text-primary-foreground",
  isDisabled && "opacity-50 cursor-not-allowed",
)} />

Project rules

All routes are declared in src/features/ui/index.tsx using WrappedRoute. Lazy-loaded components are registered in src/features/ui/util/async-components.ts.

<WrappedRoute
  path="/notifications"
  page={BundleContainer}
  component={Notifications}
  requiresAuth
/>

requiresAuth redirects unauthenticated users to login automatically — you don't need to handle that in the feature component. Auth routes (login, register, OTP) live in src/features/auth-layout/.

import { defineMessages, useIntl } from "react-intl";

const messages = defineMessages({
  follow: { id: "account.follow", defaultMessage: "Follow" },
});

const FollowButton = () => {
  const intl = useIntl();
  return <button>{intl.formatMessage(messages.follow)}</button>;
};

After adding any message, run npm run i18n — it extracts all messages into src/locales/en.json. Never hand-edit en.json.

We use Vitest — Jest-compatible and Vite-native. Tests live alongside their subjects (src/features/compose/__tests__/) or in src/__tests__/. Mock modules are in src/__mocks__/.

Branching

We work on GitLab. The main branch is main. For any piece of work, create a feature branch off main with a descriptive name (e.g. fix/chat-unread-count, feat/group-join-button). Make focused, atomic commits — each commit should represent one logical change.

Opening a Merge Request

When your branch is ready, push it and open an MR against main on GitLab. Fill out the MR template completely:

Code review

Reviews are formal but not adversarial — the goal is shared understanding and code quality. Expect comments on correctness, convention adherence, and whether an existing utility could be reused. Respond to every comment, either with a change or a brief explanation. Mark threads resolved once addressed. Don't merge your own MR without approval.

CI pipeline

Every push triggers the pipeline automatically. All three test-stage jobs must pass before your MR can merge.

Pre-push checklist

When you encounter an unfamiliar screen or need to understand how something works, always start at the route and work inward. Here's the pattern to follow — use the notifications screen as a concrete example.

Step 1 — Find the route

Open src/features/ui/index.tsx and search for the URL path. Every screen in the app is registered here with WrappedRoute.

// Search for the path string, e.g. "/notifications"
<WrappedRoute
  path="/notifications"
  component={Notifications}
  page={BundleContainer}
  requiresAuth
/>

Step 2 — Find the component

The component prop is a lazy-loaded reference. Open src/features/ui/util/async-components.ts and search for the component name to find the actual file path.

// In async-components.ts
export const Notifications = lazy(() =>
  import("@/features/alerts/components/alerts-index")
);

Step 3 — Open the feature component

Navigate to the resolved path (src/features/alerts/components/alerts-index.tsx in this case). Read the component top-down:

Step 4 — Find the API hook

The hook imported by the component lives in src/api/<feature>/hooks/. Open it and note:

• The endpoint string — this is the API path being called
• The schema — find it in src/schemas/ to see what fields the app expects
• The queryKey — tells you how this data is cached and what else might share or invalidate it

Step 5 — Verify in the Network tab

Load the screen in the browser with DevTools open. Filter the Network tab to Fetch/XHR and confirm the request matches the endpoint you found in code. Check the response shape against the schema. This closes the loop between what the code expects and what the API actually returns.

These tasks are designed to be approachable first contributions — each one touches a real problem in the codebase and follows the full workflow: branch → code → pre-push checklist → MR → review. Ask your team lead to point you to a specific file for each one if you're not sure where to start.