# saidattaputta/writewise-ai architecture

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

- Interactive diagram: https://gitdiagram.com/saidattaputta/writewise-ai
- Repository: https://github.com/saidattaputta/writewise-ai

## Overview

WriteWise AI is a full-stack professional letter-generation application. Users provide recipient, purpose, tone, and requirements; the backend validates the request, builds a prompt, calls Gemini, parses the response, and returns a letter that can be saved and later retrieved or deleted. Authentication supports registration and login with hashed passwords and JWTs. The README also documents templates and user/profile capabilities, but their frontend implementation is not represented in the supplied tree. Backend wiring is summarized from the README and module layout; only selected source files were sampled.

Main entry points: [`backend/app/api/v1/endpoints/letters.py`](https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/api/v1/endpoints/letters.py) (Letter endpoints), [`backend/app/api/v1/router.py`](https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/api/v1/router.py) (Versioned API router), [`backend/app/api/v1/endpoints/auth.py`](https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/api/v1/endpoints/auth.py) (Auth endpoints), [`backend/app/services/ai_service.py`](https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/services/ai_service.py) (AI service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_frontend_auth["Auth client<br/>[authService.ts]"]
  node_frontend_features["Writing UI, templates, history"]
end

subgraph group_api["API and identity"]
  node_app["Application entry<br/>[main.py]"]
  node_api_router["Versioned API router<br/>[router.py]"]
  node_auth_endpoints["Auth endpoints<br/>[auth.py]"]
  node_letter_endpoints["Letter endpoints<br/>[letters.py]"]
  node_auth_service["Auth service<br/>[auth_service.py]"]
  node_auth_helpers["JWT and password security"]
  node_auth_schema["Auth schemas<br/>[auth.py]"]
end

subgraph group_writing["Writing pipeline"]
  node_letter_schema["Letter schemas<br/>[letter.py]"]
  node_ai_service["AI service<br/>[ai_service.py]"]
  node_prompt_builder["Prompt builder<br/>[prompt_builder.py]"]
  node_llm_client["Gemini client<br/>[llm_client.py]"]
  node_response_parser["Response parser<br/>[parser.py]"]
end

subgraph group_persistence["Persistence"]
  node_user_repo["User repository<br/>[user_repository.py]"]
  node_letter_repo["Letter repository"]
  node_user_model["User model<br/>[user.py]"]
  node_letter_model["Letter model<br/>[letter.py]"]
  node_database[("PostgreSQL")]
end

node_user(("User"))
node_gemini{{"Gemini API"}}

node_user -->|"registers or logs in"| node_frontend_auth
node_frontend_auth -->|"sends auth requests"| node_api_router
node_user -->|"provides writing inputs"| node_frontend_features
node_frontend_features -->|"calls REST API"| node_api_router
node_app -->|"mounts routes"| node_api_router
node_api_router -->|"dispatches auth"| node_auth_endpoints
node_api_router -->|"dispatches letters"| node_letter_endpoints
node_auth_endpoints -->|"validates requests"| node_auth_schema
node_letter_endpoints -->|"validates requests"| node_letter_schema
node_auth_endpoints -->|"delegates auth"| node_auth_service
node_auth_service -->|"hashes and signs"| node_auth_helpers
node_auth_service -->|"looks up or creates"| node_user_repo
node_user_repo -->|"reads and writes"| node_database
node_letter_endpoints -->|"requests generation"| node_ai_service
node_ai_service -->|"builds prompt"| node_prompt_builder
node_ai_service -->|"generates text"| node_llm_client
node_llm_client -->|"sends prompt"| node_gemini
node_gemini -->|"returns response"| node_llm_client
node_ai_service -->|"cleans response"| node_response_parser
node_letter_endpoints -->|"stores and retrieves"| node_letter_repo
node_letter_repo -->|"reads and writes"| node_database
node_user_repo -->|"maps user records"| node_user_model
node_letter_repo -->|"maps letter records"| node_letter_model
node_letter_endpoints -->|"returns letter results"| node_frontend_features
node_auth_endpoints -->|"returns token or user"| node_frontend_auth

click node_frontend_auth "https://github.com/saidattaputta/writewise-ai/blob/main/frontend/src/services/authService.ts"
click node_app "https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/main.py"
click node_api_router "https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/api/v1/router.py"
click node_auth_endpoints "https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/api/v1/endpoints/auth.py"
click node_letter_endpoints "https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/api/v1/endpoints/letters.py"
click node_auth_service "https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/services/auth_service.py"
click node_auth_helpers "https://github.com/saidattaputta/writewise-ai/tree/main/backend/app/auth"
click node_auth_schema "https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/schemas/auth.py"
click node_letter_schema "https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/schemas/letter.py"
click node_ai_service "https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/services/ai_service.py"
click node_prompt_builder "https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/ai/prompt_builder.py"
click node_llm_client "https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/ai/llm_client.py"
click node_response_parser "https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/ai/parser.py"
click node_user_repo "https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/repositories/user_repository.py"
click node_letter_repo "https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/repositories/letter_repository.py"
click node_user_model "https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/models/user.py"
click node_letter_model "https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/models/letter.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_frontend_auth,node_frontend_features,node_user toneBlue
class node_app,node_api_router,node_auth_endpoints,node_letter_endpoints,node_auth_service,node_auth_helpers,node_auth_schema toneAmber
class node_letter_schema,node_ai_service,node_prompt_builder,node_llm_client,node_response_parser,node_gemini toneMint
class node_user_repo,node_letter_repo,node_user_model,node_letter_model,node_database toneRose
```

## Components

### Client

- [Auth client](https://github.com/saidattaputta/writewise-ai/blob/main/frontend/src/services/authService.ts): `frontend/src/services/authService.ts`
- **Writing UI, templates, history**

### API and identity

- [Application entry](https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/main.py): `backend/app/main.py`
- [Versioned API router](https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/api/v1/router.py): `backend/app/api/v1/router.py`
- [Auth endpoints](https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/api/v1/endpoints/auth.py): `backend/app/api/v1/endpoints/auth.py`
- [Letter endpoints](https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/api/v1/endpoints/letters.py): `backend/app/api/v1/endpoints/letters.py`
- [Auth service](https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/services/auth_service.py): `backend/app/services/auth_service.py`
- [JWT and password security](https://github.com/saidattaputta/writewise-ai/tree/main/backend/app/auth): `backend/app/auth`
- [Auth schemas](https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/schemas/auth.py): `backend/app/schemas/auth.py`

### Writing pipeline

- [Letter schemas](https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/schemas/letter.py): `backend/app/schemas/letter.py`
- [AI service](https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/services/ai_service.py): `backend/app/services/ai_service.py`
- [Prompt builder](https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/ai/prompt_builder.py): `backend/app/ai/prompt_builder.py`
- [Gemini client](https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/ai/llm_client.py): `backend/app/ai/llm_client.py`
- [Response parser](https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/ai/parser.py): `backend/app/ai/parser.py`

### Persistence

- [User repository](https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/repositories/user_repository.py): `backend/app/repositories/user_repository.py`
- [Letter repository](https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/repositories/letter_repository.py): `backend/app/repositories/letter_repository.py`
- [User model](https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/models/user.py): `backend/app/models/user.py`
- [Letter model](https://github.com/saidattaputta/writewise-ai/blob/main/backend/app/models/letter.py): `backend/app/models/letter.py`
- **PostgreSQL**

### Other components

- **User**
- **Gemini API**

## Connections

- User → Auth client: registers or logs in
- Auth client → Versioned API router: sends auth requests
- User → Writing UI, templates, history: provides writing inputs
- Writing UI, templates, history → Versioned API router: calls REST API
- Application entry → Versioned API router: mounts routes
- Versioned API router → Auth endpoints: dispatches auth
- Versioned API router → Letter endpoints: dispatches letters
- Auth endpoints → Auth schemas: validates requests
- Letter endpoints → Letter schemas: validates requests
- Auth endpoints → Auth service: delegates auth
- Auth service → JWT and password security: hashes and signs
- Auth service → User repository: looks up or creates
- User repository → PostgreSQL: reads and writes
- Letter endpoints → AI service: requests generation
- AI service → Prompt builder: builds prompt
- AI service → Gemini client: generates text
- Gemini client → Gemini API: sends prompt
- Gemini API → Gemini client: returns response
- AI service → Response parser: cleans response
- Letter endpoints → Letter repository: stores and retrieves
- Letter repository → PostgreSQL: reads and writes
- User repository → User model: maps user records
- Letter repository → Letter model: maps letter records
- Letter endpoints → Writing UI, templates, history: returns letter results
- Auth endpoints → Auth client: returns token or user