How joschan21/contentport works
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: page.tsx Studio shell · index.ts API entry · tweet-router.ts Tweet router · redis.ts External services
Components 20
Next.js app
Public marketing, auth, and authenticated studio routes rendered by the main web app.
- Landing · Marketing, pricing, testimonials, and legal/public entry routes.
src/app/page.tsx - Auth flows · Sign-in, sign-up, verification, invite, and onboarding routes.
src/app/(auth)/sign-in/page.tsx - Studio shell · Authenticated product area under /studio with the main user workspace.
src/app/studio/page.tsx - Feed · Consuming and exploring tweets/content for inspiration and context.
src/app/studio/feed/page.tsx - Knowledge · User memories and writing-style management for generation context.
src/app/studio/knowledge/page.tsx - Queue & history · Scheduled and posted post-management views inside the studio.
src/app/studio/scheduled/page.tsx - Topic monitor · 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 · App and dashboard providers plus layout scaffolding for authenticated areas.
src/components/providers/providers.tsx - Sidebar · Account-aware navigation and layout chrome for the studio.
src/components/app-sidebar.tsx - Tweet editor · Rich post composer with media, link preview, scheduling, and queue controls.
src/components/tweet-editor/tweet-editor.tsx - Chat UI · Streaming chat and message components for AI-assisted creation.
src/components/chat/messages.tsx - Account state · Account switching and per-account client state used across studio flows.
src/hooks/account-ctx.tsx - Tweet 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 · Central server composition exposed through the catch-all API route.
src/server/index.ts - Chat router · LLM-backed chat stream plus tools for content generation and web reading.
src/server/routers/chat/chat-router.ts - Tweet router · Create, queue, fetch, and manage tweet publication state.
src/server/routers/tweet/tweet-router.ts - Knowledge router · 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 · Database, cache, storage, AI, email, payment, realtime, and queue integrations.
src/lib/redis.ts - Database · Relational persistence for auth, tweet, and knowledge entities.
src/db/schema/index.ts
Transcription worker
Separate AWS Lambda package for transcription jobs.
- Transcription Lambda · Separate deployed worker package for transcription processing.
jobs/transcription/index.ts
Connections 24
- 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.