# tgaall/docflow architecture

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

- Interactive diagram: https://gitdiagram.com/tgaall/docflow
- Repository: https://github.com/tgaall/docflow

## Overview

DocFlow is a FastAPI backend for managing student practical placements and producing DOCX documents. The main workflow is to import student and organization data, manage groups, practices, supervisors and assignments, then export directions, an order or a group report. The graph includes the database/model and repository layers as well as the documented router capabilities. Source excerpts support the sampled call paths; several unsampled routers and repositories are connected only where the SOURCE INDEX lists their imports.

Main entry points: [`src/main.py`](https://github.com/tgaall/docflow/blob/main/src/main.py) (FastAPI app), [`src/routers`](https://github.com/tgaall/docflow/tree/main/src/routers) (Management routes), [`src/routers/documents.py`](https://github.com/tgaall/docflow/blob/main/src/routers/documents.py) (Document routes), [`src/db/session.py`](https://github.com/tgaall/docflow/blob/main/src/db/session.py) (Async sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and contracts"]
  node_app["FastAPI app<br/>[main.py]"]
  node_assignment_api["Assignment routes<br/>[assignments.py]"]
  node_assignment_schema["Assignment schemas<br/>[assignments.py]"]
  node_management_api["Management routes"]
  node_import_api["Import routes<br/>[imports.py]"]
  node_document_api["Document routes<br/>[documents.py]"]
  node_import_schema["Import schemas<br/>[imports.py]"]
  node_document_schema["Document schemas<br/>[documents.py]"]
end

subgraph group_domain["Placement management"]
  node_assignment_repo["Assignments<br/>[assignments.py]"]
  node_student_repo["Students and groups<br/>[students.py]"]
  node_practice_repo["Practices and supervisors<br/>[practices.py]"]
  node_organization_repo["Organizations<br/>[organizations.py]"]
  node_report_repo["Report data<br/>[reports.py]"]
  node_domain_models["Placement records<br/>[domain.py]"]
end

subgraph group_imports["Data imports"]
  node_import_service["File import<br/>[imports.py]"]
end

subgraph group_exports["Document exports"]
  node_document_service["DOCX rendering<br/>[documents.py]"]
end

subgraph group_persistence["Persistence"]
  node_database_setup["Database bootstrap<br/>[bootstrap.py]"]
  node_session["Async sessions<br/>[session.py]"]
  node_base["ORM base and URL<br/>[base.py]"]
  node_sqlite[("Practice database<br/>[practice.db]")]
end

node_client(("API client"))

node_client -->|"sends requests"| node_app
node_app -->|"registers"| node_assignment_api
node_app -->|"registers"| node_management_api
node_app -->|"registers"| node_import_api
node_app -->|"registers"| node_document_api
node_app -->|"initializes"| node_database_setup
node_assignment_api -->|"gets session"| node_session
node_assignment_api -->|"calls"| node_assignment_repo
node_assignment_api -->|"validates and returns"| node_assignment_schema
node_management_api -->|"gets session"| node_session
node_management_api -->|"calls"| node_student_repo
node_management_api -->|"calls"| node_practice_repo
node_management_api -->|"calls"| node_organization_repo
node_management_api -->|"uses contracts"| node_import_schema
node_import_api -->|"gets session"| node_session
node_import_api -->|"calls"| node_import_service
node_import_api -->|"uses contracts"| node_import_schema
node_import_service -->|"imports students"| node_student_repo
node_import_service -->|"imports organizations"| node_organization_repo
node_document_api -->|"gets session"| node_session
node_document_api -->|"reads assignment data"| node_assignment_repo
node_document_api -->|"reads report data"| node_report_repo
node_document_api -->|"renders documents"| node_document_service
node_document_api -->|"uses context"| node_document_schema
node_assignment_repo -->|"queries and updates"| node_domain_models
node_student_repo -->|"queries and creates"| node_domain_models
node_practice_repo -->|"queries and creates"| node_domain_models
node_organization_repo -->|"uses models"| node_domain_models
node_report_repo -->|"uses models"| node_domain_models
node_database_setup -->|"uses session"| node_session
node_database_setup -->|"uses ORM base"| node_base
node_database_setup -->|"loads models"| node_domain_models
node_session -->|"uses database URL"| node_base
node_base -->|"configures URL"| node_sqlite

click node_app "https://github.com/tgaall/docflow/blob/main/src/main.py"
click node_assignment_api "https://github.com/tgaall/docflow/blob/main/src/routers/assignments.py"
click node_assignment_schema "https://github.com/tgaall/docflow/blob/main/src/schemas/assignments.py"
click node_management_api "https://github.com/tgaall/docflow/tree/main/src/routers"
click node_import_api "https://github.com/tgaall/docflow/blob/main/src/routers/imports.py"
click node_document_api "https://github.com/tgaall/docflow/blob/main/src/routers/documents.py"
click node_import_schema "https://github.com/tgaall/docflow/blob/main/src/schemas/imports.py"
click node_document_schema "https://github.com/tgaall/docflow/blob/main/src/schemas/documents.py"
click node_assignment_repo "https://github.com/tgaall/docflow/blob/main/src/repositories/assignments.py"
click node_student_repo "https://github.com/tgaall/docflow/blob/main/src/repositories/students.py"
click node_practice_repo "https://github.com/tgaall/docflow/blob/main/src/repositories/practices.py"
click node_organization_repo "https://github.com/tgaall/docflow/blob/main/src/repositories/organizations.py"
click node_report_repo "https://github.com/tgaall/docflow/blob/main/src/repositories/reports.py"
click node_domain_models "https://github.com/tgaall/docflow/blob/main/src/models/domain.py"
click node_import_service "https://github.com/tgaall/docflow/blob/main/src/services/imports.py"
click node_document_service "https://github.com/tgaall/docflow/blob/main/src/services/documents.py"
click node_database_setup "https://github.com/tgaall/docflow/blob/main/src/db/bootstrap.py"
click node_session "https://github.com/tgaall/docflow/blob/main/src/db/session.py"
click node_base "https://github.com/tgaall/docflow/blob/main/src/db/base.py"
click node_sqlite "https://github.com/tgaall/docflow/blob/main/practice.db"

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_assignment_api,node_assignment_schema,node_management_api,node_import_api,node_document_api,node_import_schema,node_document_schema,node_client toneBlue
class node_assignment_repo,node_student_repo,node_practice_repo,node_organization_repo,node_report_repo,node_domain_models toneAmber
class node_import_service toneMint
class node_document_service toneRose
class node_database_setup,node_session,node_base,node_sqlite toneIndigo
```

## Components

### API and contracts

- [FastAPI app](https://github.com/tgaall/docflow/blob/main/src/main.py): `src/main.py`
- [Assignment routes](https://github.com/tgaall/docflow/blob/main/src/routers/assignments.py): `src/routers/assignments.py`
- [Assignment schemas](https://github.com/tgaall/docflow/blob/main/src/schemas/assignments.py): `src/schemas/assignments.py`
- [Management routes](https://github.com/tgaall/docflow/tree/main/src/routers): `src/routers`
- [Import routes](https://github.com/tgaall/docflow/blob/main/src/routers/imports.py): `src/routers/imports.py`
- [Document routes](https://github.com/tgaall/docflow/blob/main/src/routers/documents.py): `src/routers/documents.py`
- [Import schemas](https://github.com/tgaall/docflow/blob/main/src/schemas/imports.py): `src/schemas/imports.py`
- [Document schemas](https://github.com/tgaall/docflow/blob/main/src/schemas/documents.py): `src/schemas/documents.py`

### Placement management

- [Assignments](https://github.com/tgaall/docflow/blob/main/src/repositories/assignments.py): `src/repositories/assignments.py`
- [Students and groups](https://github.com/tgaall/docflow/blob/main/src/repositories/students.py): `src/repositories/students.py`
- [Practices and supervisors](https://github.com/tgaall/docflow/blob/main/src/repositories/practices.py): `src/repositories/practices.py`
- [Organizations](https://github.com/tgaall/docflow/blob/main/src/repositories/organizations.py): `src/repositories/organizations.py`
- [Report data](https://github.com/tgaall/docflow/blob/main/src/repositories/reports.py): `src/repositories/reports.py`
- [Placement records](https://github.com/tgaall/docflow/blob/main/src/models/domain.py): `src/models/domain.py`

### Data imports

- [File import](https://github.com/tgaall/docflow/blob/main/src/services/imports.py): `src/services/imports.py`

### Document exports

- [DOCX rendering](https://github.com/tgaall/docflow/blob/main/src/services/documents.py): `src/services/documents.py`

### Persistence

- [Database bootstrap](https://github.com/tgaall/docflow/blob/main/src/db/bootstrap.py): `src/db/bootstrap.py`
- [Async sessions](https://github.com/tgaall/docflow/blob/main/src/db/session.py): `src/db/session.py`
- [ORM base and URL](https://github.com/tgaall/docflow/blob/main/src/db/base.py): `src/db/base.py`
- [Practice database](https://github.com/tgaall/docflow/blob/main/practice.db): `practice.db`

### Other components

- **API client**

## Connections

- API client → FastAPI app: sends requests (evidence: `src/main.py`)
- FastAPI app → Assignment routes: registers (evidence: `src/main.py`)
- FastAPI app → Management routes: registers (evidence: `src/main.py`)
- FastAPI app → Import routes: registers (evidence: `src/main.py`)
- FastAPI app → Document routes: registers (evidence: `src/main.py`)
- FastAPI app → Database bootstrap: initializes (evidence: `src/main.py`)
- Assignment routes → Async sessions: gets session (evidence: `src/routers/assignments.py`)
- Assignment routes → Assignments: calls (evidence: `src/routers/assignments.py`)
- Assignment routes → Assignment schemas: validates and returns (evidence: `src/routers/assignments.py`)
- Management routes → Async sessions: gets session (evidence: `src/routers/groups.py`)
- Management routes → Students and groups: calls (evidence: `src/routers/groups.py`)
- Management routes → Practices and supervisors: calls (evidence: `src/routers/supervisors.py`)
- Management routes → Organizations: calls (evidence: `src/routers/orgs.py`)
- Management routes → Import schemas: uses contracts (evidence: `src/routers/practices.py`)
- Import routes → Async sessions: gets session (evidence: `src/routers/imports.py`)
- Import routes → File import: calls (evidence: `src/routers/imports.py`)
- Import routes → Import schemas: uses contracts (evidence: `src/routers/imports.py`)
- File import → Students and groups: imports students (evidence: `src/services/imports.py`)
- File import → Organizations: imports organizations (evidence: `src/services/imports.py`)
- Document routes → Async sessions: gets session (evidence: `src/routers/documents.py`)
- Document routes → Assignments: reads assignment data (evidence: `src/routers/documents.py`)
- Document routes → Report data: reads report data (evidence: `src/routers/documents.py`)
- Document routes → DOCX rendering: renders documents (evidence: `src/routers/documents.py`)
- Document routes → Document schemas: uses context (evidence: `src/routers/documents.py`)
- Assignments → Placement records: queries and updates (evidence: `src/repositories/assignments.py`)
- Students and groups → Placement records: queries and creates (evidence: `src/repositories/students.py`)
- Practices and supervisors → Placement records: queries and creates (evidence: `src/repositories/practices.py`)
- Organizations → Placement records: uses models (evidence: `src/repositories/organizations.py`)
- Report data → Placement records: uses models (evidence: `src/repositories/reports.py`)
- Database bootstrap → Async sessions: uses session (evidence: `src/db/bootstrap.py`)
- Database bootstrap → ORM base and URL: uses ORM base (evidence: `src/db/bootstrap.py`)
- Database bootstrap → Placement records: loads models (evidence: `src/db/bootstrap.py`)
- Async sessions → ORM base and URL: uses database URL (evidence: `src/db/session.py`)
- ORM base and URL → Practice database: configures URL (evidence: `src/db/base.py`)
