# joschan21/contentport architecture

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

- Interactive diagram: https://gitdiagram.com/joschan21/contentport
- Repository: https://github.com/joschan21/contentport

## Overview

1. **Top-level shape**
   - This is a **Next.js App Router** application in TypeScript, with a large **authenticated product surface** plus public marketing/legal pages.
   - The repo is split into a main web app (`src/app`), a shared component layer (`src/components`, `src/hooks`, `src/lib`), a backend router layer (`src/server`), and one separate AWS job package (`jobs/transcription`).

2. **Primary user-facing surfaces**
   - Public routes cover landing pages, pricing, testimonials, legal docs, auth, invite, and onboarding.
   - The core product lives under **`/studio`**, with sub-pages for **accounts, feed, knowledge, scheduled, posted, settings, and topic monitoring**.
   - This strongly suggests the product is a **social/content orchestration tool** centered on drafting, scheduling, and monitoring posts.

3. **Frontend architecture**
   - UI is built from reusable React components in `src/components`, including shared shell/layout pieces, modals, form controls, and a fairly rich **tweet editor** subsystem.
   - `src/hooks` contains the client state and interaction logic for accounts, tweets, chat, attachments, sidebar resizing, local storage, and media/tweet metadata.
   - `src/app/layout.tsx`, `src/components/providers`, and dashboard-specific providers indicate a **provider-heavy shell** for authenticated areas.

4. **Content creation and post management flow**
   - The main creation flow appears to be: **compose/edit tweet content → attach media/link previews → schedule or queue → publish → track posted/scheduled state**.
   - That flow is reflected in `tweet-editor`, `tweet-queue`, `tweet-list`, `tweet-post-confirmation-dialog`, and the studio pages for **scheduled** and **posted** content.
   - A separate **feed** area and **topic-monitor** area suggest the app also consumes social content for inspiration, replies, or monitoring.

5. **Assistant / AI subsystem**
   - `src/server/routers/chat` plus client chat components indicate an **assistant experience** that streams responses and helps generate content.
   - The chat router has tools such as **create tweet** and **read website content**, so the assistant is not just conversational; it can drive product actions and ingest external sources.
   - Supporting code like `openrouter.ts`, prompt utilities, XML prompt helpers, and response hooks indicates the app uses an **LLM-backed generation pipeline**.

6. **Knowledge and style memory**
   - There is a dedicated **knowledge subsystem**: `src/db/schema/knowledge.ts`, `src/db/queries/knowledge.ts`, and `src/server/routers/knowledge-router.ts`.
   - Studio tabs like **memories** and **writing style** imply the app stores user-specific context and style preferences to shape generated posts.
   - `src/lib/vector.ts` suggests some knowledge items may be embedded or indexed for semantic retrieval.

7. **Backend/API boundary**
   - Backend logic is centralized in `src/server`, with routers for **auth, chat, email, feed, file, knowledge, settings, stripe, style, and tweet**.
   - `src/app/api/[[...route]]/route.ts` acts as a **catch-all API boundary**, and `src/server/jstack.ts` suggests a typed router/RPC-style server composition.
   - This keeps business logic out of React components and makes the API layer the main integration point for the frontend.

8. **Persistence and stateful infrastructure**
   - `src/db/schema` defines the core persisted entities: **auth, knowledge, and tweet**.
   - The app uses `drizzle.config.ts`, so the database layer is **Drizzle ORM** over a relational database.
   - Additional stateful services include **Redis** (`src/lib/redis.ts`) for ephemeral state/coordination, and **S3** (`src/lib/s3.ts`) for media storage.

9. **External product integrations**
   - **Stripe** is a first-class subsystem: there are product/subscription constants, a Stripe webhook route, a Stripe server router, and a seed script.
   - The product also integrates with **social account connections** and media upload/fetch utilities, implying tight coupling to the external social platform API used for posting.
   - `firecrawl.ts` indicates website fetching/scraping is used as an input source for content generation or research.
   - Email templates live in `src/emails`, with a dedicated email router for outbound notifications.

10. **Async/background processing**
   - `src/lib/qstash.ts`, tweet polling utilities, and queue helpers point to **queued/background workflows** for delayed publishing and status checks.
   - `src/lib/realtime.ts` and `src/app/api/realtime/route.ts` indicate live updates for long-running operations such as generation, posting, or queue changes.
   - The separate `jobs/transcription` package is an **AWS CDK-deployed Lambda** with tests and a dedicated entrypoint, used to process transcription work outside the main app.

11. **Auth and account boundary**
   - Authentication has its own app routes (`sign-in`, `sign-up`, token verification) and API route (`src/app/api/auth/[...all]/route.ts`).
   - `middleware.ts` likely enforces route protection and redirects between public/authenticated areas.
   - `account-connection` and `account-switcher` components indicate the app is **multi-account aware**, with account context affecting most studio flows.

12. **Operational shape**
   - The app is designed as a **single web product with several integration-heavy subsystems** rather than a set of independent services.
   - The main architecture boundaries are: **UI shell**, **typed backend routers**, **database/state services**, **external platform integrations**, and a **separate transcription worker**.
   - If you draw a diagram, the key central node is the studio web app, connected outward to auth, DB, Redis, S3, Stripe, social APIs, AI/LLM services, email, and the transcription Lambda.

Main entry points: [`src/app/studio/page.tsx`](https://github.com/joschan21/contentport/blob/main/src/app/studio/page.tsx) (Studio shell), [`src/server/index.ts`](https://github.com/joschan21/contentport/blob/main/src/server/index.ts) (API entry), [`src/server/routers/tweet/tweet-router.ts`](https://github.com/joschan21/contentport/blob/main/src/server/routers/tweet/tweet-router.ts) (Tweet router), [`src/lib/redis.ts`](https://github.com/joschan21/contentport/blob/main/src/lib/redis.ts) (External services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Next.js app"]
  node_home["Landing<br/>public pages<br/>[page.tsx]"]
  node_auth["Auth flows<br/>auth pages<br/>[page.tsx]"]
  node_studio["Studio shell<br/>app routes<br/>[page.tsx]"]
  node_studio_feed["Feed<br/>studio view<br/>[page.tsx]"]
  node_studio_knowledge["Knowledge<br/>studio view<br/>[page.tsx]"]
  node_studio_content["Queue & history<br/>studio views<br/>[page.tsx]"]
  node_studio_topics["Topic monitor<br/>studio view<br/>[page.tsx]"]
end

subgraph group_ui["Shared UI"]
  node_shell["Providers<br/>react shell<br/>[providers.tsx]"]
  node_sidebar["Sidebar<br/>navigation shell<br/>[app-sidebar.tsx]"]
  node_editor["Tweet editor<br/>composer<br/>[tweet-editor.tsx]"]
  node_chat_ui["Chat UI<br/>assistant ui<br/>[messages.tsx]"]
  node_account_ctx["Account state<br/>client state<br/>[account-ctx.tsx]"]
  node_tweet_state["Tweet state<br/>client state<br/>[use-tweets-v2.tsx]"]
end

subgraph group_backend["Server layer"]
  node_server["API entry<br/>typed server<br/>[index.ts]"]
  node_chat_api["Chat router<br/>assistant api<br/>[chat-router.ts]"]
  node_tweet_api["Tweet router<br/>post api<br/>[tweet-router.ts]"]
  node_knowledge_api["Knowledge router<br/>memory api"]
end

subgraph group_data["Data & infra"]
  node_integrations["External services<br/>infra services<br/>[redis.ts]"]
  node_db[("Database<br/>drizzle schema<br/>[index.ts]")]
end

subgraph group_worker["Transcription worker"]
  node_worker_pkg{{"Transcription Lambda<br/>aws cdk package<br/>[index.ts]"}}
end

node_home -->|"entry to auth"| node_auth
node_home -->|"enter product"| node_studio
node_auth -->|"verify session"| node_server
node_studio -->|"uses shell"| node_shell
node_studio -->|"navigates via"| node_sidebar
node_studio -->|"includes"| node_studio_feed
node_studio -->|"includes"| node_studio_knowledge
node_studio -->|"includes"| node_studio_content
node_studio -->|"includes"| node_studio_topics
node_studio_feed -->|"reads content"| node_tweet_api
node_studio_knowledge -->|"edits memory"| node_knowledge_api
node_editor -->|"creates posts"| node_tweet_api
node_editor -->|"client state"| node_tweet_state
node_chat_ui -->|"streams chat"| node_chat_api
node_chat_api -->|"LLM + web"| node_integrations
node_tweet_api -->|"queue + media"| node_integrations
node_knowledge_api -->|"stores memories"| node_db
node_tweet_api -->|"stores tweets"| node_db
node_server -->|"mounts"| node_chat_api
node_server -->|"mounts"| node_tweet_api
node_server -->|"mounts"| node_knowledge_api
node_server -->|"uses infra"| node_integrations
node_integrations -->|"persistence"| node_db
node_integrations -.->|"async offload"| node_worker_pkg

click node_home "https://github.com/joschan21/contentport/blob/main/src/app/page.tsx"
click node_auth "https://github.com/joschan21/contentport/blob/main/src/app/(auth)/sign-in/page.tsx"
click node_studio "https://github.com/joschan21/contentport/blob/main/src/app/studio/page.tsx"
click node_studio_feed "https://github.com/joschan21/contentport/blob/main/src/app/studio/feed/page.tsx"
click node_studio_knowledge "https://github.com/joschan21/contentport/blob/main/src/app/studio/knowledge/page.tsx"
click node_studio_content "https://github.com/joschan21/contentport/blob/main/src/app/studio/scheduled/page.tsx"
click node_studio_topics "https://github.com/joschan21/contentport/blob/main/src/app/studio/topic-monitor/page.tsx"
click node_shell "https://github.com/joschan21/contentport/blob/main/src/components/providers/providers.tsx"
click node_sidebar "https://github.com/joschan21/contentport/blob/main/src/components/app-sidebar.tsx"
click node_editor "https://github.com/joschan21/contentport/blob/main/src/components/tweet-editor/tweet-editor.tsx"
click node_chat_ui "https://github.com/joschan21/contentport/blob/main/src/components/chat/messages.tsx"
click node_account_ctx "https://github.com/joschan21/contentport/blob/main/src/hooks/account-ctx.tsx"
click node_tweet_state "https://github.com/joschan21/contentport/blob/main/src/hooks/use-tweets-v2.tsx"
click node_server "https://github.com/joschan21/contentport/blob/main/src/server/index.ts"
click node_chat_api "https://github.com/joschan21/contentport/blob/main/src/server/routers/chat/chat-router.ts"
click node_tweet_api "https://github.com/joschan21/contentport/blob/main/src/server/routers/tweet/tweet-router.ts"
click node_knowledge_api "https://github.com/joschan21/contentport/blob/main/src/server/routers/knowledge-router.ts"
click node_integrations "https://github.com/joschan21/contentport/blob/main/src/lib/redis.ts"
click node_db "https://github.com/joschan21/contentport/blob/main/src/db/schema/index.ts"
click node_worker_pkg "https://github.com/joschan21/contentport/blob/main/jobs/transcription/index.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_home,node_auth,node_studio,node_studio_feed,node_studio_knowledge,node_studio_content,node_studio_topics toneBlue
class node_shell,node_sidebar,node_editor,node_chat_ui,node_account_ctx,node_tweet_state toneAmber
class node_server,node_chat_api,node_tweet_api,node_knowledge_api toneMint
class node_integrations,node_db toneRose
class node_worker_pkg toneIndigo
```

## Components

### Next.js app

Public marketing, auth, and authenticated studio routes rendered by the main web app.

- [Landing](https://github.com/joschan21/contentport/blob/main/src/app/page.tsx): public pages · Marketing, pricing, testimonials, and legal/public entry routes. · `src/app/page.tsx`
- [Auth flows](https://github.com/joschan21/contentport/blob/main/src/app/(auth)/sign-in/page.tsx): auth pages · Sign-in, sign-up, verification, invite, and onboarding routes. · `src/app/(auth)/sign-in/page.tsx`
- [Studio shell](https://github.com/joschan21/contentport/blob/main/src/app/studio/page.tsx): app routes · Authenticated product area under /studio with the main user workspace. · `src/app/studio/page.tsx`
- [Feed](https://github.com/joschan21/contentport/blob/main/src/app/studio/feed/page.tsx): studio view · Consuming and exploring tweets/content for inspiration and context. · `src/app/studio/feed/page.tsx`
- [Knowledge](https://github.com/joschan21/contentport/blob/main/src/app/studio/knowledge/page.tsx): studio view · User memories and writing-style management for generation context. · `src/app/studio/knowledge/page.tsx`
- [Queue & history](https://github.com/joschan21/contentport/blob/main/src/app/studio/scheduled/page.tsx): studio views · Scheduled and posted post-management views inside the studio. · `src/app/studio/scheduled/page.tsx`
- [Topic monitor](https://github.com/joschan21/contentport/blob/main/src/app/studio/topic-monitor/page.tsx): studio view · Monitoring, quoting, and commenting workflow for tracked topics. · `src/app/studio/topic-monitor/page.tsx`

### Shared UI

Reusable client components, shells, editors, and interaction hooks.

- [Providers](https://github.com/joschan21/contentport/blob/main/src/components/providers/providers.tsx): react shell · App and dashboard providers plus layout scaffolding for authenticated areas. · `src/components/providers/providers.tsx`
- [Sidebar](https://github.com/joschan21/contentport/blob/main/src/components/app-sidebar.tsx): navigation shell · Account-aware navigation and layout chrome for the studio. · `src/components/app-sidebar.tsx`
- [Tweet editor](https://github.com/joschan21/contentport/blob/main/src/components/tweet-editor/tweet-editor.tsx): composer · Rich post composer with media, link preview, scheduling, and queue controls. · `src/components/tweet-editor/tweet-editor.tsx`
- [Chat UI](https://github.com/joschan21/contentport/blob/main/src/components/chat/messages.tsx): assistant ui · Streaming chat and message components for AI-assisted creation. · `src/components/chat/messages.tsx`
- [Account state](https://github.com/joschan21/contentport/blob/main/src/hooks/account-ctx.tsx): client state · Account switching and per-account client state used across studio flows. · `src/hooks/account-ctx.tsx`
- [Tweet state](https://github.com/joschan21/contentport/blob/main/src/hooks/use-tweets-v2.tsx): client state · Tweet/editor/attachment state, metadata, and local interaction logic. · `src/hooks/use-tweets-v2.tsx`

### Server layer

Typed API routers and server utilities behind the catch-all route.

- [API entry](https://github.com/joschan21/contentport/blob/main/src/server/index.ts): typed server · Central server composition exposed through the catch-all API route. · `src/server/index.ts`
- [Chat router](https://github.com/joschan21/contentport/blob/main/src/server/routers/chat/chat-router.ts): assistant api · LLM-backed chat stream plus tools for content generation and web reading. · `src/server/routers/chat/chat-router.ts`
- [Tweet router](https://github.com/joschan21/contentport/blob/main/src/server/routers/tweet/tweet-router.ts): post api · Create, queue, fetch, and manage tweet publication state. · `src/server/routers/tweet/tweet-router.ts`
- [Knowledge router](https://github.com/joschan21/contentport/blob/main/src/server/routers/knowledge-router.ts): memory api · Persisted memories and writing-style data used to steer generation. · `src/server/routers/knowledge-router.ts`

### Data & infra

Persistence, external services, and async/background execution.

- [External services](https://github.com/joschan21/contentport/blob/main/src/lib/redis.ts): infra services · Database, cache, storage, AI, email, payment, realtime, and queue integrations. · `src/lib/redis.ts`
- [Database](https://github.com/joschan21/contentport/blob/main/src/db/schema/index.ts): drizzle schema · Relational persistence for auth, tweet, and knowledge entities. · `src/db/schema/index.ts`

### Transcription worker

Separate AWS Lambda package for transcription jobs.

- [Transcription Lambda](https://github.com/joschan21/contentport/blob/main/jobs/transcription/index.ts): aws cdk package · Separate deployed worker package for transcription processing. · `jobs/transcription/index.ts`

## Connections

- Landing → Auth flows: entry to auth · Public visitors move into sign-in, sign-up, onboarding, and invite flows.
- Landing → Studio shell: enter product · Authenticated users reach the main studio workspace from the public surface.
- Auth flows → API entry: verify session · Auth pages and verification routes rely on the server/auth boundary.
- Studio shell → Providers: uses shell · Studio routes are wrapped in shared providers and dashboard layout state.
- Studio shell → Sidebar: navigates via · Authenticated workspace uses the shared sidebar and account-aware navigation.
- Studio shell → Feed: includes · The studio surface includes feed exploration and content discovery.
- Studio shell → Knowledge: includes · The studio surface includes memories and writing-style management.
- Studio shell → Queue & history: includes · The studio surface includes scheduled and posted content history.
- Studio shell → Topic monitor: includes · The studio surface includes topic monitoring and response workflows.
- Feed → Tweet router: reads content · Feed and topic surfaces consume tweet-related data and actions from the backend.
- Knowledge → Knowledge router: edits memory · Knowledge screens persist memories and style preferences through the knowledge router.
- Tweet editor → Tweet router: creates posts · The composer drives drafting, queuing, scheduling, and publishing actions.
- Tweet editor → Tweet state: client state · Editor behavior is powered by tweet and attachment state hooks.
- Chat UI → Chat router: streams chat · Chat components render streaming assistant responses from the chat router.
- Chat router → External services: LLM + web · Chat uses generation providers and website-fetch utilities for assistance and research.
- Tweet router → External services: queue + media · Tweet publishing relies on queues, realtime updates, storage, and external posting integrations.
- Knowledge router → Database: stores memories · Knowledge data is persisted in relational tables and queried centrally.
- Tweet router → Database: stores tweets · Tweet state, scheduling, and post history are persisted in the database.
- API entry → Chat router: mounts · The central server composes the chat router into the API surface.
- API entry → Tweet router: mounts · The central server composes tweet management into the API surface.
- API entry → Knowledge router: mounts · The central server composes knowledge management into the API surface.
- API entry → External services: uses infra · Server routers depend on shared infrastructure clients and utilities.
- External services → Database: persistence · Core services ultimately read and write the relational database.
- External services → Transcription Lambda: async offload · Background transcription is handled outside the main app by a separate Lambda package.
