# alansteves/postforge architecture

> Architecture diagram of the GitHub repository alansteves/postforge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alansteves/postforge
- Repository: https://github.com/alansteves/postforge

## Overview

PostForge AI is a LinkedIn-content creation app: users discuss an idea in chat, turn it into a polished post, preview and edit it, then connect LinkedIn and publish. The sampled API routes show generation, formatting, preference and post persistence, plus session-backed authentication. The graph also preserves the documented-in-source OAuth and publishing surfaces. Several client hooks and routes were not excerpted, so their wiring is shown only where supported; unverified integration links are dashed.

Main entry points: [`lib/db/prisma.ts`](https://github.com/alansteves/postforge/blob/main/lib/db/prisma.ts) (PostgreSQL database), [`context/post-context.tsx`](https://github.com/alansteves/postforge/blob/main/context/post-context.tsx) (Post context), [`app/api/ai/generate/route.ts`](https://github.com/alansteves/postforge/blob/main/app/api/ai/generate/route.ts) (Chat generation API), [`lib/auth/session.ts`](https://github.com/alansteves/postforge/blob/main/lib/auth/session.ts) (Session management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Creator experience"]
  node_chat_ui["Chat interface"]
  node_context["Post context<br/>[post-context.tsx]"]
  node_hooks["Client state hooks"]
end

subgraph group_content["Content workflow"]
  node_generate["Chat generation API<br/>[route.ts]"]
  node_formatter["Post formatting API<br/>[route.ts]"]
  node_preferences["Preference API and controls<br/>[route.ts]"]
  node_preview["Post preview and actions"]
  node_posts_api["Post endpoints"]
  node_conversations_api["Conversation endpoints"]
end

subgraph group_identity["Identity and preferences"]
  node_auth_ui["Sign-in and signup"]
  node_auth_api["Auth endpoints"]
  node_session["Session management<br/>[session.ts]"]
  node_passwords["Password hashing<br/>[auth.ts]"]
  node_sanitizer["User sanitization<br/>[sanitizer.ts]"]
end

subgraph group_integrations["External services"]
  node_linkedin_api["LinkedIn endpoints"]
  node_gemini["Gemini API"]
  node_linkedin["LinkedIn"]
end

subgraph group_storage["Persistence"]
  node_database[("PostgreSQL database<br/>[prisma.ts]")]
end

node_creator(("Creator"))

node_creator -->|"signs in"| node_auth_ui
node_auth_ui -->|"uses auth state"| node_context
node_auth_api -->|"checks credentials"| node_passwords
node_auth_api -->|"creates session"| node_session
node_session -->|"loads user"| node_database
node_session -->|"sanitizes user"| node_sanitizer
node_context -->|"composes state"| node_hooks
node_creator -.->|"submits idea"| node_chat_ui
node_chat_ui -.->|"uses chat state"| node_context
node_creator -->|"sends prompt"| node_generate
node_generate -->|"requests completion"| node_gemini
node_generate -->|"stores messages"| node_database
node_creator -->|"requests formatting"| node_formatter
node_formatter -->|"reads preferences and saves post"| node_database
node_creator -->|"updates preferences"| node_preferences
node_preferences -->|"reads and writes settings"| node_database
node_creator -->|"manages drafts"| node_posts_api
node_posts_api -->|"reads and writes posts"| node_database
node_creator -.->|"manages conversations"| node_conversations_api
node_conversations_api -->|"reads and writes conversations"| node_database
node_context -->|"provides post state"| node_preview
node_creator -->|"reviews and edits"| node_preview
node_preview -->|"connects or disconnects"| node_context
node_context -.->|"requests account and publish actions"| node_linkedin_api
node_linkedin_api -.->|"uses OAuth and publishing"| node_linkedin
node_linkedin_api -->|"loads account and post data"| node_database

click node_auth_ui "https://github.com/alansteves/postforge/tree/main/components/auth"
click node_auth_api "https://github.com/alansteves/postforge/tree/main/app/api/auth"
click node_session "https://github.com/alansteves/postforge/blob/main/lib/auth/session.ts"
click node_passwords "https://github.com/alansteves/postforge/blob/main/lib/auth.ts"
click node_sanitizer "https://github.com/alansteves/postforge/blob/main/lib/sanitizer.ts"
click node_chat_ui "https://github.com/alansteves/postforge/tree/main/components/chat"
click node_context "https://github.com/alansteves/postforge/blob/main/context/post-context.tsx"
click node_hooks "https://github.com/alansteves/postforge/tree/main/lib/hooks"
click node_generate "https://github.com/alansteves/postforge/blob/main/app/api/ai/generate/route.ts"
click node_formatter "https://github.com/alansteves/postforge/blob/main/app/api/posts/format/route.ts"
click node_preferences "https://github.com/alansteves/postforge/blob/main/app/api/preferences/route.ts"
click node_preview "https://github.com/alansteves/postforge/tree/main/components/post-preview"
click node_posts_api "https://github.com/alansteves/postforge/tree/main/app/api/posts"
click node_conversations_api "https://github.com/alansteves/postforge/tree/main/app/api/conversations"
click node_linkedin_api "https://github.com/alansteves/postforge/tree/main/app/api/linkedin"
click node_database "https://github.com/alansteves/postforge/blob/main/lib/db/prisma.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_chat_ui,node_context,node_hooks toneBlue
class node_generate,node_formatter,node_preferences,node_preview,node_posts_api,node_conversations_api toneAmber
class node_auth_ui,node_auth_api,node_session,node_passwords,node_sanitizer toneMint
class node_linkedin_api,node_gemini,node_linkedin toneRose
class node_database,node_creator toneIndigo
```

## Components

### Creator experience

- [Chat interface](https://github.com/alansteves/postforge/tree/main/components/chat): `components/chat`
- [Post context](https://github.com/alansteves/postforge/blob/main/context/post-context.tsx): `context/post-context.tsx`
- [Client state hooks](https://github.com/alansteves/postforge/tree/main/lib/hooks): `lib/hooks`

### Content workflow

- [Chat generation API](https://github.com/alansteves/postforge/blob/main/app/api/ai/generate/route.ts): `app/api/ai/generate/route.ts`
- [Post formatting API](https://github.com/alansteves/postforge/blob/main/app/api/posts/format/route.ts): `app/api/posts/format/route.ts`
- [Preference API and controls](https://github.com/alansteves/postforge/blob/main/app/api/preferences/route.ts): `app/api/preferences/route.ts`
- [Post preview and actions](https://github.com/alansteves/postforge/tree/main/components/post-preview): `components/post-preview`
- [Post endpoints](https://github.com/alansteves/postforge/tree/main/app/api/posts): `app/api/posts`
- [Conversation endpoints](https://github.com/alansteves/postforge/tree/main/app/api/conversations): `app/api/conversations`

### Identity and preferences

- [Sign-in and signup](https://github.com/alansteves/postforge/tree/main/components/auth): `components/auth`
- [Auth endpoints](https://github.com/alansteves/postforge/tree/main/app/api/auth): `app/api/auth`
- [Session management](https://github.com/alansteves/postforge/blob/main/lib/auth/session.ts): `lib/auth/session.ts`
- [Password hashing](https://github.com/alansteves/postforge/blob/main/lib/auth.ts): `lib/auth.ts`
- [User sanitization](https://github.com/alansteves/postforge/blob/main/lib/sanitizer.ts): `lib/sanitizer.ts`

### External services

- [LinkedIn endpoints](https://github.com/alansteves/postforge/tree/main/app/api/linkedin): `app/api/linkedin`
- **Gemini API**
- **LinkedIn**

### Persistence

- [PostgreSQL database](https://github.com/alansteves/postforge/blob/main/lib/db/prisma.ts): `lib/db/prisma.ts`

### Other components

- **Creator**

## Connections

- Creator → Sign-in and signup: signs in
- Sign-in and signup → Post context: uses auth state (evidence: `components/auth/sign-in-form.tsx`)
- Auth endpoints → Password hashing: checks credentials (evidence: `app/api/auth/sign-in/route.ts`)
- Auth endpoints → Session management: creates session (evidence: `app/api/auth/sign-in/route.ts`)
- Session management → PostgreSQL database: loads user (evidence: `lib/auth/session.ts`)
- Session management → User sanitization: sanitizes user (evidence: `lib/auth/session.ts`)
- Post context → Client state hooks: composes state (evidence: `context/post-context.tsx`)
- Creator → Chat interface: submits idea
- Chat interface → Post context: uses chat state (evidence: `components/chat/recent-searches.tsx`)
- Creator → Chat generation API: sends prompt (evidence: `app/api/ai/generate/route.ts`)
- Chat generation API → Gemini API: requests completion (evidence: `app/api/ai/generate/route.ts`)
- Chat generation API → PostgreSQL database: stores messages (evidence: `app/api/ai/generate/route.ts`)
- Creator → Post formatting API: requests formatting (evidence: `app/api/posts/format/route.ts`)
- Post formatting API → PostgreSQL database: reads preferences and saves post (evidence: `app/api/posts/format/route.ts`)
- Creator → Preference API and controls: updates preferences (evidence: `app/api/preferences/route.ts`)
- Preference API and controls → PostgreSQL database: reads and writes settings (evidence: `app/api/preferences/route.ts`)
- Creator → Post endpoints: manages drafts (evidence: `app/api/posts/route.ts`)
- Post endpoints → PostgreSQL database: reads and writes posts (evidence: `app/api/posts/route.ts`)
- Creator → Conversation endpoints: manages conversations
- Conversation endpoints → PostgreSQL database: reads and writes conversations (evidence: `app/api/conversations/route.ts`)
- Post context → Post preview and actions: provides post state (evidence: `components/post-preview/post-preview.tsx`)
- Creator → Post preview and actions: reviews and edits
- Post preview and actions → Post context: connects or disconnects (evidence: `components/post-preview/post-preview.tsx`)
- Post context → LinkedIn endpoints: requests account and publish actions
- LinkedIn endpoints → LinkedIn: uses OAuth and publishing
- LinkedIn endpoints → PostgreSQL database: loads account and post data (evidence: `app/api/linkedin/publish/route.ts`)
