# mustafaabdullahai-dev/postcraft-linkedin architecture

> Architecture diagram of the GitHub repository mustafaabdullahai-dev/postcraft-linkedin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mustafaabdullahai-dev/postcraft-linkedin
- Repository: https://github.com/mustafaabdullahai-dev/postcraft-linkedin

## Overview

PostCraft is a multi-user LinkedIn content drafting, review, scheduling, and publishing platform. Users sign in with LinkedIn or as guests, submit a topic, and review an AI-generated post and image before approving, scheduling, or publishing it. The README also documents voice profiles, editing aids, filtering, export, and audit logging. The graph captures the documented workflow and major capabilities; source excerpts are partial, so uncertain route-to-service wiring is omitted. Provider and persistence details are represented at the documented subsystem level.

Main entry points: [`backend/app/agents/nodes/content_nodes.py`](https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/agents/nodes/content_nodes.py) (Generation nodes), [`backend/app/main.py`](https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/main.py) (FastAPI app), [`frontend/src/App.tsx`](https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/frontend/src/App.tsx) (Dashboard), [`backend/app/api/routes/posts.py`](https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/api/routes/posts.py) (Post routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["Dashboard<br/>[App.tsx]"]
  node_auth_ui["Sign-in UI<br/>[LoginScreen.tsx]"]
  node_client_auth["Session client<br/>[auth.ts]"]
  node_client_api["REST client<br/>[api.ts]"]
end

subgraph group_api["API and identity"]
  node_server["FastAPI app<br/>[main.py]"]
  node_auth_routes["Auth routes<br/>[auth.py]"]
  node_post_routes["Post routes<br/>[posts.py]"]
  node_voice_routes["Voice routes<br/>[voice.py]"]
  node_linkedin_routes["LinkedIn routes<br/>[linkedin.py]"]
end

subgraph group_generation["Content generation"]
  node_workflow["Agent workflow<br/>[graph.py]"]
  node_content_nodes["Generation nodes<br/>[content_nodes.py]"]
  node_prompts["Prompt templates<br/>[content.py]"]
  node_text_service["Text provider<br/>[llm.py]"]
  node_validator["Quality validator<br/>[validator.py]"]
  node_image_service["Image generation"]
end

subgraph group_lifecycle["Post lifecycle"]
  node_post_store[("Post store<br/>[post.py]")]
  node_voice_store[("Voice profiles<br/>[voice.py]")]
  node_scheduler["Scheduler<br/>[scheduler.py]"]
end

subgraph group_integrations["Persistence and integrations"]
  node_publisher["LinkedIn publisher<br/>[linkedin.py]"]
  node_sheets["Audit logging<br/>[google_sheets.py]"]
  node_analytics["Engagement analytics<br/>[analytics.py]"]
end

node_user(("Author"))
node_linkedin{{"LinkedIn"}}
node_text_models{{"Text model providers"}}
node_image_models{{"Image model providers"}}
node_sheets_service{{"Google Sheets"}}

node_user -->|"uses"| node_app
node_app -->|"shows"| node_auth_ui
node_auth_ui -->|"starts session"| node_client_auth
node_app -->|"checks session"| node_client_auth
node_app -->|"requests data"| node_client_api
node_client_auth -->|"calls auth API"| node_server
node_client_api -->|"calls API"| node_server
node_server -->|"dispatches"| node_auth_routes
node_server -->|"dispatches"| node_post_routes
node_server -->|"dispatches"| node_voice_routes
node_server -->|"dispatches"| node_linkedin_routes
node_post_routes -->|"runs generation"| node_workflow
node_workflow -->|"dispatches stages"| node_content_nodes
node_content_nodes -->|"uses prompts"| node_prompts
node_content_nodes -->|"requests text"| node_text_service
node_text_service -.->|"invokes"| node_text_models
node_content_nodes -->|"validates draft"| node_validator
node_content_nodes -->|"requests image"| node_image_service
node_image_service -.->|"invokes"| node_image_models
node_post_routes -->|"reads and writes"| node_post_store
node_voice_routes -->|"reads and writes"| node_voice_store
node_post_routes -->|"publishes approved"| node_publisher
node_scheduler -->|"loads scheduled posts"| node_post_store
node_scheduler -->|"publishes due posts"| node_publisher
node_publisher -.->|"publishes as user"| node_linkedin
node_linkedin_routes -->|"requests analytics"| node_analytics
node_analytics -->|"uses LinkedIn client"| node_publisher
node_content_nodes -->|"records audit"| node_sheets
node_sheets -.->|"writes rows"| node_sheets_service

click node_app "https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/frontend/src/App.tsx"
click node_auth_ui "https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/frontend/src/components/LoginScreen.tsx"
click node_client_auth "https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/frontend/src/services/auth.ts"
click node_client_api "https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/frontend/src/services/api.ts"
click node_server "https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/main.py"
click node_auth_routes "https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/api/routes/auth.py"
click node_post_routes "https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/api/routes/posts.py"
click node_voice_routes "https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/api/routes/voice.py"
click node_linkedin_routes "https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/api/routes/linkedin.py"
click node_workflow "https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/agents/graph.py"
click node_content_nodes "https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/agents/nodes/content_nodes.py"
click node_prompts "https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/prompts/content.py"
click node_text_service "https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/services/llm.py"
click node_validator "https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/services/validator.py"
click node_image_service "https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/services/image_generation.py"
click node_post_store "https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/models/post.py"
click node_voice_store "https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/models/voice.py"
click node_scheduler "https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/services/scheduler.py"
click node_publisher "https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/services/linkedin.py"
click node_sheets "https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/services/google_sheets.py"
click node_analytics "https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/services/analytics.py"

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_app,node_auth_ui,node_client_auth,node_client_api toneBlue
class node_server,node_auth_routes,node_post_routes,node_voice_routes,node_linkedin_routes toneAmber
class node_workflow,node_content_nodes,node_prompts,node_text_service,node_validator,node_image_service toneMint
class node_post_store,node_voice_store,node_scheduler toneRose
class node_publisher,node_sheets,node_analytics,node_user,node_linkedin,node_text_models,node_image_models,node_sheets_service toneIndigo
```

## Components

### Web client

- [Dashboard](https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Sign-in UI](https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/frontend/src/components/LoginScreen.tsx): `frontend/src/components/LoginScreen.tsx`
- [Session client](https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/frontend/src/services/auth.ts): `frontend/src/services/auth.ts`
- [REST client](https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### API and identity

- [FastAPI app](https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/main.py): `backend/app/main.py`
- [Auth routes](https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/api/routes/auth.py): `backend/app/api/routes/auth.py`
- [Post routes](https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/api/routes/posts.py): `backend/app/api/routes/posts.py`
- [Voice routes](https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/api/routes/voice.py): `backend/app/api/routes/voice.py`
- [LinkedIn routes](https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/api/routes/linkedin.py): `backend/app/api/routes/linkedin.py`

### Content generation

- [Agent workflow](https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/agents/graph.py): `backend/app/agents/graph.py`
- [Generation nodes](https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/agents/nodes/content_nodes.py): `backend/app/agents/nodes/content_nodes.py`
- [Prompt templates](https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/prompts/content.py): `backend/app/prompts/content.py`
- [Text provider](https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/services/llm.py): `backend/app/services/llm.py`
- [Quality validator](https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/services/validator.py): `backend/app/services/validator.py`
- [Image generation](https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/services/image_generation.py): `backend/app/services/image_generation.py`

### Post lifecycle

- [Post store](https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/models/post.py): `backend/app/models/post.py`
- [Voice profiles](https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/models/voice.py): `backend/app/models/voice.py`
- [Scheduler](https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/services/scheduler.py): `backend/app/services/scheduler.py`

### Persistence and integrations

- [LinkedIn publisher](https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/services/linkedin.py): `backend/app/services/linkedin.py`
- [Audit logging](https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/services/google_sheets.py): `backend/app/services/google_sheets.py`
- [Engagement analytics](https://github.com/mustafaabdullahai-dev/postcraft-linkedin/blob/main/backend/app/services/analytics.py): `backend/app/services/analytics.py`

### Other components

- **Author**
- **LinkedIn**
- **Text model providers**
- **Image model providers**
- **Google Sheets**

## Connections

- Author → Dashboard: uses
- Dashboard → Sign-in UI: shows
- Sign-in UI → Session client: starts session
- Dashboard → Session client: checks session
- Dashboard → REST client: requests data
- Session client → FastAPI app: calls auth API
- REST client → FastAPI app: calls API
- FastAPI app → Auth routes: dispatches
- FastAPI app → Post routes: dispatches
- FastAPI app → Voice routes: dispatches
- FastAPI app → LinkedIn routes: dispatches
- Post routes → Agent workflow: runs generation
- Agent workflow → Generation nodes: dispatches stages
- Generation nodes → Prompt templates: uses prompts
- Generation nodes → Text provider: requests text
- Text provider → Text model providers: invokes
- Generation nodes → Quality validator: validates draft
- Generation nodes → Image generation: requests image
- Image generation → Image model providers: invokes
- Post routes → Post store: reads and writes
- Voice routes → Voice profiles: reads and writes
- Post routes → LinkedIn publisher: publishes approved
- Scheduler → Post store: loads scheduled posts
- Scheduler → LinkedIn publisher: publishes due posts
- LinkedIn publisher → LinkedIn: publishes as user
- LinkedIn routes → Engagement analytics: requests analytics
- Engagement analytics → LinkedIn publisher: uses LinkedIn client
- Generation nodes → Audit logging: records audit
- Audit logging → Google Sheets: writes rows