# mushfiq13/collabnote architecture

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

- Interactive diagram: https://gitdiagram.com/mushfiq13/collabnote
- Repository: https://github.com/mushfiq13/collabnote

## Overview

1. **System shape**
   CollabNote is split into two runtime processes: a **FastAPI API service** under `app/` and a separate **Kafka consumer worker** under `consumer/`. Supporting infrastructure is wired around them with **PostgreSQL, MongoDB, Elasticsearch, Redis, Kafka, and Nginx**, typically started together via `docker-compose.yml`.

2. **API entrypoint and route surface**
   `app/main.py` is the HTTP entrypoint for the ASGI app. Based on the README, it exposes the main user-facing flows: authentication (`/auth/signup`, `/auth/login`), note creation (`/notes`), note retrieval (`/notes/{id}`), and search (`/search`).

3. **Authentication and authorization boundary**
   `app/auth.py` encapsulates signup/login, password hashing, and JWT token handling. The auth flow is built on **bcrypt/passlib** for password storage and **python-jose** for Bearer tokens, with protected endpoints requiring `Authorization: Bearer <token>`.

4. **Relational data path**
   `app/database.py`, `app/models.py`, and the Alembic tree define the **PostgreSQL** side of the system. The README makes clear this store is used for user account/profile data, while Alembic migrations manage schema evolution. This is the durable relational boundary.

5. **Document storage path**
   `app/mongodb.py` represents the **MongoDB** integration, likely using Motor for async access. The main read/write note document lifecycle lives here: note creation stores the note document, and note reads fall back to MongoDB when Redis misses.

6. **Search indexing path**
   `app/elasticsearch.py` is the search integration boundary. After a note is created, the note is indexed into **Elasticsearch**, which powers fuzzy search and ranked results with highlighting on `GET /search?q=...`.

7. **Caching path**
   `app/redis_client.py` is the **Redis** integration for hot note reads. The read flow is explicitly cache-first: `GET /notes/{id}` hits Redis for sub-2 ms responses when warm, and on cache miss it loads from MongoDB and populates the cache.

8. **Event streaming and side effects**
   `app/kafka_producer.py` publishes domain events from the API, especially `signup` and `create_note`. These events are not the primary data source; they are the integration mechanism for asynchronous side effects and observability.

9. **Background consumer**
   `consumer/consumer.py` is a separate worker that consumes Kafka events and writes them to MongoDB for logging/audit-style persistence. This is the main asynchronous branch of the architecture, distinct from the synchronous request/response path.

10. **Validation and contract layer**
   `app/schemas.py` contains the Pydantic request/response models that define the API contract. Together with the database models, this separates external payload validation from persistence concerns.

11. **Infrastructure and edge**
   `nginx/nginx.conf` indicates Nginx sits in front of the app as the load balancer/reverse proxy. `docker-compose.yml` suggests the full stack is containerized for local and deployment parity, with environment values supplied from `.env`.

12. **Migrations, CI, and tests**
   `alembic/` is the migration boundary for PostgreSQL schema changes. `.github/workflows/ci.yml` handles automated CI/CD, and `tests/test_api.py` appears to cover the acceptance flows described in the README, especially auth, note creation, search, and cache/read behavior.

Main entry points: [`app/main.py`](https://github.com/mushfiq13/collabnote/blob/main/app/main.py) (API app), [`docker-compose.yml`](https://github.com/mushfiq13/collabnote/blob/main/docker-compose.yml) (Compose), [`app/database.py`](https://github.com/mushfiq13/collabnote/blob/main/app/database.py) (SQL store), [`app/mongodb.py`](https://github.com/mushfiq13/collabnote/blob/main/app/mongodb.py) (MongoDB)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API service"]
  node_app_main["API app<br/>FastAPI entrypoint<br/>[main.py]"]
  node_app_auth["Auth<br/>[auth.py]"]
  node_app_schemas["Schemas<br/>Pydantic contract<br/>[schemas.py]"]
  node_app_kafka["Producer<br/>Kafka publisher<br/>[kafka_producer.py]"]
end

subgraph group_worker["Worker"]
  node_consumer_worker["Consumer<br/>Kafka worker<br/>[consumer.py]"]
end

subgraph group_data["Data layer"]
  node_app_db[("SQL store<br/>PostgreSQL access<br/>[database.py]")]
  node_app_models["Models<br/>[models.py]"]
  node_app_mongo[("MongoDB<br/>document store<br/>[mongodb.py]")]
  node_app_redis[("Redis cache<br/>cache client<br/>[redis_client.py]")]
  node_app_es[("Search<br/>[elasticsearch.py]")]
end

subgraph group_infra["Infra"]
  node_alembic["Migrations<br/>Alembic schema<br/>[env.py]"]
  node_nginx["Nginx<br/>reverse proxy<br/>[nginx.conf]"]
  node_compose["Compose<br/>stack orchestration<br/>[docker-compose.yml]"]
  node_ci["CI<br/>GitHub Actions<br/>[ci.yml]"]
  node_tests["API tests<br/>pytest suite<br/>[test_api.py]"]
end

node_nginx -->|"routes"| node_app_main
node_app_main -->|"auth"| node_app_auth
node_app_main -->|"validates"| node_app_schemas
node_app_main -->|"users"| node_app_db
node_app_main -->|"notes"| node_app_mongo
node_app_main -->|"cache"| node_app_redis
node_app_main -->|"search"| node_app_es
node_app_main -->|"events"| node_app_kafka
node_app_auth -->|"stores"| node_app_db
node_app_db -->|"maps"| node_app_models
node_alembic -->|"migrates"| node_app_db
node_app_es -->|"results"| node_app_main
node_app_redis -->|"hits"| node_app_main
node_app_mongo -->|"misses"| node_app_main
node_app_kafka -->|"streams"| node_consumer_worker
node_consumer_worker -->|"writes"| node_app_mongo
node_compose -->|"includes"| node_nginx
node_compose -->|"runs"| node_app_main
node_compose -->|"runs"| node_consumer_worker
node_compose -->|"provisions"| node_app_db
node_compose -->|"provisions"| node_app_mongo
node_compose -->|"provisions"| node_app_es
node_compose -->|"provisions"| node_app_redis
node_compose -->|"provisions"| node_app_kafka
node_ci -->|"executes"| node_tests
node_tests -->|"covers"| node_app_main

click node_app_main "https://github.com/mushfiq13/collabnote/blob/main/app/main.py"
click node_app_auth "https://github.com/mushfiq13/collabnote/blob/main/app/auth.py"
click node_app_schemas "https://github.com/mushfiq13/collabnote/blob/main/app/schemas.py"
click node_app_db "https://github.com/mushfiq13/collabnote/blob/main/app/database.py"
click node_app_models "https://github.com/mushfiq13/collabnote/blob/main/app/models.py"
click node_alembic "https://github.com/mushfiq13/collabnote/blob/main/alembic/env.py"
click node_app_mongo "https://github.com/mushfiq13/collabnote/blob/main/app/mongodb.py"
click node_app_redis "https://github.com/mushfiq13/collabnote/blob/main/app/redis_client.py"
click node_app_es "https://github.com/mushfiq13/collabnote/blob/main/app/elasticsearch.py"
click node_app_kafka "https://github.com/mushfiq13/collabnote/blob/main/app/kafka_producer.py"
click node_consumer_worker "https://github.com/mushfiq13/collabnote/blob/main/consumer/consumer.py"
click node_nginx "https://github.com/mushfiq13/collabnote/blob/main/nginx/nginx.conf"
click node_compose "https://github.com/mushfiq13/collabnote/blob/main/docker-compose.yml"
click node_ci "https://github.com/mushfiq13/collabnote/blob/main/.github/workflows/ci.yml"
click node_tests "https://github.com/mushfiq13/collabnote/blob/main/tests/test_api.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_main,node_app_auth,node_app_schemas,node_app_kafka toneBlue
class node_consumer_worker toneAmber
class node_app_db,node_app_models,node_app_mongo,node_app_redis,node_app_es toneMint
class node_alembic,node_nginx,node_compose,node_ci,node_tests toneRose
```

## Components

### API service

FastAPI request path and supporting application boundaries

- [API app](https://github.com/mushfiq13/collabnote/blob/main/app/main.py): FastAPI entrypoint · ASGI service exposing auth, notes, and search routes · `app/main.py`
- [Auth](https://github.com/mushfiq13/collabnote/blob/main/app/auth.py): JWT auth · Signup, login, password hashing, and bearer token handling · `app/auth.py`
- [Schemas](https://github.com/mushfiq13/collabnote/blob/main/app/schemas.py): Pydantic contract · Request and response models for API validation · `app/schemas.py`
- [Producer](https://github.com/mushfiq13/collabnote/blob/main/app/kafka_producer.py): Kafka publisher · Publishes domain events such as signup and note creation · `app/kafka_producer.py`

### Worker

Asynchronous Kafka consumer process

- [Consumer](https://github.com/mushfiq13/collabnote/blob/main/consumer/consumer.py): Kafka worker · Background process consuming events and persisting audit-style data · `consumer/consumer.py`

### Data layer

Primary persistence, cache, and search systems

- [SQL store](https://github.com/mushfiq13/collabnote/blob/main/app/database.py): PostgreSQL access · Relational connection and user/account persistence · `app/database.py`
- [Models](https://github.com/mushfiq13/collabnote/blob/main/app/models.py): ORM models · Database entities and persistence mapping for relational data · `app/models.py`
- [MongoDB](https://github.com/mushfiq13/collabnote/blob/main/app/mongodb.py): document store · Async note document persistence and read fallback · `app/mongodb.py`
- [Redis cache](https://github.com/mushfiq13/collabnote/blob/main/app/redis_client.py): cache client · Hot note read cache for low-latency lookups · `app/redis_client.py`
- [Search](https://github.com/mushfiq13/collabnote/blob/main/app/elasticsearch.py): Elasticsearch · Note indexing and fuzzy search with highlighting · `app/elasticsearch.py`

### Infra

Deployment, proxy, migrations, CI, and tests

- [Migrations](https://github.com/mushfiq13/collabnote/blob/main/alembic/env.py): Alembic schema · PostgreSQL schema evolution and version history · `alembic/env.py`
- [Nginx](https://github.com/mushfiq13/collabnote/blob/main/nginx/nginx.conf): reverse proxy · Edge proxy in front of the application service · `nginx/nginx.conf`
- [Compose](https://github.com/mushfiq13/collabnote/blob/main/docker-compose.yml): stack orchestration · Container composition for app, worker, and backing services · `docker-compose.yml`
- [CI](https://github.com/mushfiq13/collabnote/blob/main/.github/workflows/ci.yml): GitHub Actions · Automated validation workflow · `.github/workflows/ci.yml`
- [API tests](https://github.com/mushfiq13/collabnote/blob/main/tests/test_api.py): pytest suite · Acceptance coverage for auth, notes, search, and cache behavior · `tests/test_api.py`

## Connections

- Nginx → API app: routes · Reverse proxy forwards HTTP traffic to the FastAPI app
- API app → Auth: auth · Login and signup flows use the auth boundary
- API app → Schemas: validates · Request and response payloads are validated through schemas
- API app → SQL store: users · Account and profile data use the relational store
- API app → MongoDB: notes · Note retrieval and storage use MongoDB as the document source
- API app → Redis cache: cache · Read path checks Redis before falling back to MongoDB
- API app → Search: search · Search endpoint queries Elasticsearch
- API app → Producer: events · API publishes domain events for async side effects
- Auth → SQL store: stores · User records and password hashes are persisted in PostgreSQL
- SQL store → Models: maps · ORM models define the relational schema boundary
- Migrations → SQL store: migrates · Migrations evolve the PostgreSQL schema
- Search → API app: results · Search results flow back to the API layer
- Redis cache → API app: hits · Warm cache responses serve note reads quickly
- MongoDB → API app: misses · Cache misses load note documents from MongoDB
- Producer → Consumer: streams · Kafka carries API-emitted domain events to the worker
- Consumer → MongoDB: writes · Worker persists consumed events into MongoDB
- Compose → Nginx: includes · Stack composition wires the reverse proxy into the deployment
- Compose → API app: runs · Compose starts the API service
- Compose → Consumer: runs · Compose starts the Kafka consumer worker
- Compose → SQL store: provisions · Compose brings up PostgreSQL
- Compose → MongoDB: provisions · Compose brings up MongoDB
- Compose → Search: provisions · Compose brings up Elasticsearch
- Compose → Redis cache: provisions · Compose brings up Redis
- Compose → Producer: provisions · Compose brings up Kafka
- CI → API tests: executes · CI runs the API test suite
- API tests → API app: covers · Tests exercise auth, note, search, and cache flows