Merge pull request #22 from moov-io/documentation

Documentation

.gitignore

@@ -18,6 +18,7 @@ coverage.html
 
 # OpenAPITools/openapi-generator
 openapi-generator-cli-*.jar
+/client/
 
 # macOS
 .DS_Store

README.md

@@ -26,53 +26,216 @@
 [![Twitter](https://img.shields.io/twitter/follow/moov?style=social)](https://twitter.com/moov?lang=en)
 
 # fincen
-Fincen (Financial crimes enforcment network) BSA data transmission methods for the the BSA E-Filing System
+Moov's mission is to give developers an easy way to create and integrate bank processing into their own software products. Our open source projects are each focused on solving a single responsibility in financial services and designed around performance, scalability, and ease of use.
+
+Moov's fincen project implements a reader, writer, and validator for Fincen BSA forms in an HTTP server and Go library.
+
+Fincen (Financial crimes enforcment network) BSA data transmission methods for the the BSA E-Filing System.
 
 A go library for reading and writing Fincen BSA forms. It is capable of generating, validating, and batching submissions.
 
-The project is Fincen which is a financial reporting for the United States. There are many forms that are required in this project but we will start with SAR(Suspicious activity report). I would like a go library that creates the structs to build and validate the SAR form. It also needs to be able to export the file to XML.
+The HTTP server is available in a Docker image and the Go package github.com/moov-io/fincen is available.
+
+
+## Table of contents
+
+- [Project status](#project-status)
+- [Supported Forms](#supported-forms)
+- [Usage](#usage)
+    - As an API
+        - [Docker](#docker)
+        - [Google Cloud](#google-cloud-run-button)
+        - [HTTP API](#http-api)
+    - [As a Go module](#go-library)
+      - [Build report form](#build-report-form)
+    - [As a command line tool](#command-line)
+    - [As an in-browser parser](##in-browser-fincen-form-parser)
+- [Learn About Fincen](#learn-about-fincen)
+- [FAQ](#faq)
+- [Getting help](#getting-help)
+- [Supported and tested platforms](#supported-and-tested-platforms)
+- [Contributing](#contributing) 
+- [License](#license)
+
+## Project status
 
-In the future we will wrap the service with json/http services so that it can work as a web service and not just a go library.
-New project
-https://github.com/moov-io/fincen/blob/master/README.md
+The project is Fincen which is a financial reporting for the United States.
 
-We will end up with a sub project for each of the form parsers. This is all of the forms.
+There are many forms that are required in this project. **Now implemented XML forms only in following link**.
+(Non XML form will implement in another sub project)
 https://bsaefiling.fincen.treas.gov/FilingInformation.html
 
 The final phase of the project will be a service that collects fillings and then on a scheduled time will batch the fillings and submit them electronically.
 https://bsaefiling.fincen.treas.gov/docs/SDTMRequirements.pdf
 
-
-[About the BSA E-Filing System](https://bsaefiling.fincen.treas.gov/AboutBsa.html)
-
 ## Supported Forms
 
-- FinCEN Currency Transaction Report (FinCEN Report 112)
+- FinCEN Currency Transaction Report (FinCEN Report 112) 
 - FinCEN Designation of Exempt Person (FinCEN Report 110)
 - FinCEN Suspicious Activity Report (FinCEN Report 111)
-- FinCEN Registration of Money Services Business (FinCEN Report 107)
 - Report of Foreign Bank and Financial Accounts (FinCEN Report 114)
 - Report of Cash Payments Over $10,000 Received in a Trade or Business (FinCEN Form 8300)
 
-## Filing information user guides
+## Usage
+The Fincen project implements an HTTP server and [Go library](https://pkg.go.dev/github.com/moov-io/fincen) for creating and modifying Fincen BSA forms.
+
+### Docker
+
+We publish a [public Docker image `moov/fincen`](https://hub.docker.com/r/moov/fincen/tags) on Docker Hub with every tagged release of Fincen.
+<!--
+We also have Docker images for [OpenShift](https://quay.io/repository/moov/fincen?tab=tags) published as `quay.io/moov/fincen`.
+-->
+
+Pull & start the Docker image:
+```
+docker pull moov/fincen:latest
+docker run -p 8088:8088 -p 9098:9098 moov/fincen:latest
+```
+
+Validate a file on the HTTP server:
+```
+curl -X POST --data-binary "@./data/samples/ctr_batch.txt" http://localhost:8088/validator
+```
+```
+{"status":"valid file"}
+```
+
+Reformat the file with generated attributes:
+```
+curl -X POST --data-binary "@./data/samples/ctr_batch.txt" http://localhost:8088/reformat
+```
+```
+<EFilingBatchXML ActivityCount="1" TotalAmount="47000" PartyCount="6" SeqNum="1"
+                     xsi:schemaLocation="www.fincen.gov/base https://www.fincen.gov/base https://www.fincen.gov/base/EFL_8300XBatchSchema.xsd"
+                     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                     xmlns:fc2="www.fincen.gov/base">
+    <Activity SeqNum="1">
+...
+```
+
+### Google Cloud Run
+
+To get started in a hosted environment you can deploy this project to the Google Cloud Platform.
+
+From your [Google Cloud dashboard](https://console.cloud.google.com/home/dashboard) create a new project and call it:
+```
+moov-fincen-demo
+```
+
+Enable the [Container Registry](https://cloud.google.com/container-registry) API for your project and associate a [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account) if needed. Then, open the Cloud Shell terminal and run the following Docker commands, substituting your unique project ID:
+
+```
+docker pull moov/fincen
+docker tag moov/fincen gcr.io/<PROJECT-ID>/fincen
+docker push gcr.io/<PROJECT-ID>/fincen
+```
+
+Deploy the container to Cloud Run:
+```
+gcloud run deploy --image gcr.io/<PROJECT-ID>/fincen --port 8088
+```
+
+Select your target platform to `1`, service name to `fincen`, and region to the one closest to you (enable Google API service if a prompt appears). Upon a successful build you will be given a URL where the API has been deployed:
+
+```
+https://YOUR-FINCEN-APP-URL.a.run.app
+```
+
+Now you can list files stored in-memory:
+```
+curl https://YOUR-FINCEN-APP-URL.a.run.app/files
+```
+You should get this response:
+```
+null
+```
 
-The [Filing Information](https://bsaefiling.fincen.treas.gov/FilingInformation.html) website contains PDF's of each of the XML formates. The PDF's guides contain links to XSD's of the formts.
+### Go library
 
-## Become a BSA E-Filer
+This project uses [Go Modules](https://github.com/golang/go/wiki/Modules) and uses Go v1.14 or higher. See [Golang's install instructions](https://golang.org/doc/install) for help setting up Go. You can download the source code and we offer [tagged and released versions](https://github.com/moov-io/fincen/releases/latest) as well. We highly recommend you use a tagged release for production.
 
-[Secure Direct Transfer Mode](https://bsaefiling.fincen.treas.gov/SDTMInfo.html)
+```
+$ [email protected]:moov-io/fincen.git
 
-[Supervisory User Registration](https://bsaefiling1.fincen.treas.gov/AddUser)
+# Pull down into the Go Module cache
+$ go get -u github.com/moov-io/fincen
+```
+The package [`github.com/moov-io/fincen`](https://pkg.go.dev/github.com/moov-io/fincen) offers a Go-based Fincen file reader and writer.
+
+### Build report form
+
+**Creating XML Batch Reporting form**
+
+Fincen project used general XML batch reporting form struct.
+Available types are "SUBMISSION", "CTRX", "SARX", "DOEPX", "FBARX", "8300X" 
+
+```
+// create report with type
+newReport := NewReport("SUBMISSION")
+```
+
+**Adding activities by each type**
+
+Activity should add into the form struct using sub package 
+
+```
+// create activity (ctr)
+var newActivity currency_transaction.ActivityType
+
+...
+setting newActivity
+...
+
+err := newReport.AppendActivity(&newActivity)
+```
+
+**Generating new xml attributes**
+```
+err = newReport.GenerateAttrs()
+```
+
+**Validating report form**
+```
+err = newReport.Validate()
+```
+
+### In-browser Fincen form parser
+Using our [in-browser utility](http://oss.moov.io/fincen/), you can instantly verify and reformat Fincen BSA forms.
+
+## Learn about Fincen
+- [About the BSA E-Filing System](https://bsaefiling.fincen.treas.gov/AboutBsa.html)
+- [Secure Direct Transfer Mode](https://bsaefiling.fincen.treas.gov/SDTMInfo.html)
+- [Supervisory User Registration](https://bsaefiling1.fincen.treas.gov/AddUser)
+
+
+## FAQ
+<details open="true">
+<summary ><b>Is there an in-browser tool?</b></summary>
+Yes! You can find our browser utility at http://oss.moov.io/fincen/.
+</details>
 
 ## Getting help
 
- channel | info
+channel | info
  ------- | -------
 [Project Documentation](https://moov-io.github.io/fincen/) | Our project documentation available online.
 Twitter [@moov](https://twitter.com/moov)	| You can follow Moov.io's Twitter feed to get updates on our project(s). You can also tweet us questions or just share blogs or stories.
 [GitHub Issue](https://github.com/moov-io/fincen/issues/new) | If you are able to reproduce a problem please open a GitHub Issue under the specific project that caused the error.
 [moov-io slack](https://slack.moov.io/) | Join our slack channel to have an interactive discussion about the development of the project.
 
+## Supported and tested platforms
+
+- 64-bit Linux (Ubuntu, Debian), macOS, and Windows
+
+Note: 32-bit platforms have known issues and are not supported.
+
+## Contributing
+
+Yes please! Please review our [Contributing guide](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md) to get started!
+
+This project uses [Go Modules](https://github.com/golang/go/wiki/Modules) and uses Go v1.19 or higher. See [Golang's install instructions](https://golang.org/doc/install) for help setting up Go. You can download the source code and we offer [tagged and released versions](https://github.com/moov-io/fincen/releases/latest) as well. We highly recommend you use a tagged release for production.
+
+
 ## License
 
 Apache License 2.0 - See [LICENSE](LICENSE) for details.

cmd/fincen/summary.go

@@ -16,7 +16,7 @@ import (
 
 func Reformat(paths []string, generate bool, newType string) ([]byte, error) {
 	fmt.Fprintf(os.Stdout, "\nFormating report file...\n")
-	r, err := batch.CreateReportFromFile(paths[0])
+	r, err := batch.CreateReportWithFile(paths[0])
 	if err != nil {
 		fmt.Fprintf(os.Stdout, "Failed to create report from file: %v\n", err)
 		return nil, err
@@ -44,7 +44,7 @@ func Reformat(paths []string, generate bool, newType string) ([]byte, error) {
 
 func Validate(paths []string) error {
 	fmt.Fprintf(os.Stdout, "\nValidating report file...\n")
-	r, err := batch.CreateReportFromFile(paths[0])
+	r, err := batch.CreateReportWithFile(paths[0])
 	if err != nil {
 		fmt.Fprintf(os.Stdout, "Failed to create report from file: %v\n", err)
 		return err
@@ -66,7 +66,7 @@ func Summary(paths []string) error {
 
 func summaryForm(path string) error {
 
-	r, err := batch.CreateReportFromFile(path)
+	r, err := batch.CreateReportWithFile(path)
 	if err != nil {
 		fmt.Fprintf(os.Stdout, "Failed to create report from file: %v\n", err)
 		fmt.Fprintf(os.Stdout, "Trying to summary file anyway...\n")

cmd/webui/fincen/fincen_js.go

@@ -23,7 +23,7 @@ func generateAttrs() js.Func {
 			return "Invalid number of arguments passed"
 		}
 
-		r, err := batch.NewReport([]byte(args[0].String()))
+		r, err := batch.CreateReportWithBuffer([]byte(args[0].String()))
 		if err != nil {
 			fmt.Println(err)
 			return "Unable to parse report file"
@@ -56,7 +56,7 @@ func validateForm() js.Func {
 			return "Invalid number of arguments passed"
 		}
 
-		r, err := batch.NewReport([]byte(args[0].String()))
+		r, err := batch.CreateReportWithBuffer([]byte(args[0].String()))
 		if err != nil {
 			fmt.Println(err)
 			return "Unable to parse report file"

docs/api/index.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>Moov FINCEN Endpoints</title>
+  <script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
+</head>
+<body>
+  <rapi-doc
+    heading-text="Moov ACH"
+    render-style="read"
+    spec-url="https://raw.githubusercontent.com/moov-io/fincen/master/openapi.yaml">
+  </rapi-doc>
+</body>
+</html>

docs/cash-payments.md

@@ -9,3 +9,23 @@ menubar: docs-menu
 # Overview
 
 Cash Payments over $10k (FinCEN Form 8300)
+
+
+Cash payments report can create using fincen go library
+
+1. Create a [EFilingBatchXML](https://godoc.org/github.com/moov-io/fincen/pkg/batch#EFilingBatchXML) with `batch.NewReport("SARX")`.
+2. Create available [ActivityType](https://godoc.org/github.com/moov-io/pkg/cash_payments#ActivityType) records with `cash_payments.NewActivity()`.
+3. Append created activities into Batch XML report with `batch.AppendActivity(activity)`.
+4. Validate Batch XML report with `Validate()` and figure out report problems.
+5. Generate Batch XML report attributes with `GenerateAttrs()`
+6. Getting xml contents from Batch XML report.
+
+# Create an acknowledgement
+
+FinCEN SAR XML batch acknowledgement can create using fincen go library
+
+1. Create a [EFilingBatchXML](https://godoc.org/github.com/moov-io/fincen/pkg/batch#EFilingBatchXML) with `batch.NewReport("SARX")`.
+2. Create a [EFilingSubmissionXML](https://godoc.org/github.com/moov-io/pkg/batch#EFilingSubmissionXML).
+3. Validate Batch XML report with `Validate()` and figure out report problems.
+4. Generate Batch XML report attributes with `GenerateAttrs()`
+5. Getting xml contents from Batch XML report.

docs/ctr.md

@@ -9,3 +9,24 @@ menubar: docs-menu
 # Overview
 
 Currency Transaction Report (CTR) - Report 112
+
+# Create a report
+
+Currency transaction report can create using fincen go library
+
+1. Create a [EFilingBatchXML](https://godoc.org/github.com/moov-io/fincen/pkg/batch#EFilingBatchXML) with `batch.NewReport("SARX")`.
+2. Create available [ActivityType](https://godoc.org/github.com/moov-io/pkg/currency_transaction#ActivityType) records with `currency_transaction.NewActivity()`.
+3. Append created activities into Batch XML report with `batch.AppendActivity(activity)`.
+4. Validate Batch XML report with `Validate()` and figure out report problems.
+5. Generate Batch XML report attributes with `GenerateAttrs()`
+6. Getting xml contents from Batch XML report.
+
+# Create an acknowledgement
+
+FinCEN SAR XML batch acknowledgement can create using fincen go library
+
+1. Create a [EFilingBatchXML](https://godoc.org/github.com/moov-io/fincen/pkg/batch#EFilingBatchXML) with `batch.NewReport("SARX")`.
+2. Create a [EFilingSubmissionXML](https://godoc.org/github.com/moov-io/pkg/batch#EFilingSubmissionXML).
+3. Validate Batch XML report with `Validate()` and figure out report problems.
+4. Generate Batch XML report attributes with `GenerateAttrs()`
+5. Getting xml contents from Batch XML report.

docs/doep.md

@@ -9,3 +9,24 @@ menubar: docs-menu
 # Overview
 
 Designation of Exempt Person (DOEP) - Form 110
+
+# Create a report
+
+Designation of exempt person can create using fincen go library
+
+1. Create a [EFilingBatchXML](https://godoc.org/github.com/moov-io/fincen/pkg/batch#EFilingBatchXML) with `batch.NewReport("SARX")`.
+2. Create available [ActivityType](https://godoc.org/github.com/moov-io/pkg/exempt_designation#ActivityType) records with `exempt_designation.NewActivity()`.
+3. Append created activities into Batch XML report with `batch.AppendActivity(activity)`.
+4. Validate Batch XML report with `Validate()` and figure out report problems.
+5. Generate Batch XML report attributes with `GenerateAttrs()`
+6. Getting xml contents from Batch XML report.
+
+# Create an acknowledgement
+
+FinCEN SAR XML batch acknowledgement can create using fincen go library
+
+1. Create a [EFilingBatchXML](https://godoc.org/github.com/moov-io/fincen/pkg/batch#EFilingBatchXML) with `batch.NewReport("SARX")`.
+2. Create a [EFilingSubmissionXML](https://godoc.org/github.com/moov-io/pkg/batch#EFilingSubmissionXML).
+3. Validate Batch XML report with `Validate()` and figure out report problems.
+4. Generate Batch XML report attributes with `GenerateAttrs()`
+5. Getting xml contents from Batch XML report.